Apple Macintosh Early Technical Information • Inside Macintosh 




Early Macintosh Technical Information 

Inside Macintosh 

QuickDraw: A Programmer's Guide 



Comment 

Very early Inside Macintosh QuickDraw 

chapter showing quickdraws early 

structure from 1982 and also editing by 

Caroline Rose of Chris Espinosas somewhat 

rough draft 

Author 

Apple Computer 

Date 

15 February 1982 

Source 

David T Craig • January 2004 



QuickDraw Programmer's Guide • 15 February 1982 Page 0001 of 0064 



Apple Macintosh Early Technical Information • Inside Macintosh 



& x 



.# 



.v 



»v 



^' 



V 







QuickDraw: A Programmer's Guide 



See Also: 



Modification History: First Draft 

Revised and Edited 



MACINTOSH PUBLICATIONS \lj Q^l^hv 



/QUICK. DRAW/QUIKDRAW 



C. Espinosa 11/27/81 
C. Espinosa 2/15/82 



ABSTRACT 



This document describes the QuickDraw graphics package, heart of the 
Macintosh User Interface ToolBox routines. It describes the 
conceptual and physical data types used by QuickDraw, the procedures 
and functions available in QuickDraw, and the details of preparing, 
compiling, and linking a program for use on the Macintosh. 
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INTRODUCTION TO QUICKDRAW 



INTRODUCTION TO QUICKDRAW 



QuickDraw is a set of graphics procedures, functions, and data types 
that allow a Pascal or assembly-language programmer of Macintosh to 
perforin highly complex graphic operations very easily and very quickly. 

This document introduces you to QuickDraw and its programmatic 
interface. It covers the graphic concepts behind QuickDraw, as well as 
the technical details of the data types, procedures, and functions you 
will use in your programs. It also describes the fundamentals of 
preparing, compiling, and linking a program to run on Macintosh. 



y 



What QuickDraw Can Do 



QuickDraw allows you to divide the Macintosh screen into a number of 
individual areas, *»& within each area you can draw many things:- 






O 



' Straight lines of any length and width; 

■filled /*- 



J. 



- Rectangles, either solid or hollow; 

- Circles and ovals, also either soli 

- Rectangles with rounded corners, solid or hollow 






Circles and ovals, also either solid or hollow; j ^ ^\{£u p CA/ \ / ^ J [j..d. 






■*M<^ f 



- Any other arbitrary shape or collection of shapes, again either / ^TV" 2 ^ . -a£#_ 
solid or hollow; ^Ju **£jfy. '{+$£ 



- Images defined dot-by-dot and stored in a file or in the program 
itself; 

- Text characters in a number_£f__proportionally-spaced fonts, with 
/ariations that include<^enSoldenI?tg N , italicizing, shadowing, and 
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Figure 1. Samples of QuickDraw's Abilities 

V- 

In addition, QuicDraw has some other abilities that you won't find in 
many other graphics packages. These abilities take care of most of the 
" housekeeping"^ the trivial but time-consuming overhead that's 
necessary to keep things stralgh&ened . up-b ttfc- oro ■ aoal-l y bothorcoma to 

ilr. iTnnrrnl f i Amnno the mm . ar a; I/* flif-JW , 

lJ £ rt Jh Q w<'C k bt A. c-v— 



d o y o urself i 



Among theae-are. 

l^VMJcexjLi^-A <Jhi us*. (m «--« *-^<* J"W — ^^ 

- The ability to define many distinct "ports" on the screen, /ecly 
with Its own complete drawing environment)!) its own coordinate 
system, drawing location, charact er set, location on the screen, 
etc. You can switch from one(arawin g environme ntfio another with 
just one command. < ' ' j „ ? , - , ; C ^j 

- Full and complete 'clipping to arbitrary rcglono . It's like a 
super-duper coloring book that won't let you color outside of the 
lines. You don't have to worry about accidentally drawing over 
something else on the screen, or drawing off the screen and 

trashing memory. 

- Off -screen drawing. Anything you can draw on the screen, you can 
draw Into an off -screen buffer, so you can prepare an image for an 
output device without disturbing the screen, or you can prepare a 
picture and move it onto the screen very quickly. 

And QuickDraw lives up to its name! It is very fast. The speed and 
responsiveness of the Macintosh user interface is due primarily to the 
speed of the QuickDraw package. You can do good-quality animation, 
fast interactive graphics, and complex yet speedy text displays using 
the full features of QuickDraw. f)\jU} / 4 ^u<u<- ..*j<rK.. f^jt>^' "t ^Ca^€-> 
-/t> kv\\^t-± y "flu- ^p^J^^' p^^f-^^- Cpcu,o/^-$ euvr Ul< .?hd^i W_ 
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How To Use QuickDraw 



QuickDraw has no user interface of its own; you must write and compile ^ 
e nr- oc=omkio> a Pacral ( nr assemhlv-lanBuaBel nrocram that includes the X'j ^ 



< 



(or assemble) a Pascal (or assembly-language) program that includes the *U 



t 



proper QuickDraw calls, link the resulting object code with the 
QuickDraw code, and execute the linked object file. 



^ 



Some programming models are supplied at. the end of this manual; they 
show the structure of a properl^organized QuickDraw prog-ram. Wha t's 
best for beginners is to obtain a'machine-readable version ot^oTIeof 
these. programs (see the Macintosh software coordinator), read through 
the -«S&, and using the superstructure of the program as a "shell", 
modify ~%t) to suit your own purposes. Once you get the hang of writing 
programs inside the presupplied shell, you can work on changing the 
shell itself. 

In the final Macintoshes, QuickDraw will be stored permanently in the 
ROM memory (right now, it resides in high RAM). All access is made 
through an indirection table in low RAM. When you write a program that 
uses QuickDraw, you link it with this indirection table. Each time you 
call a QuickDraw procedure or function, or load a predefined constant . v 
the request goes through the table into QuickDraw. You'll never access 
any QuickDraw address directly, nor will you have to code constant 
addresses into your program. The linker will make sure all address 
references get straightened out. 

QuickDraw can be used from either Pascal or(68000 / taachine language. To 
be clear, concise, and more intuitive, this manual gives all examples 
in their Pascal form; a section near the end describes the details of 
the machine language interface to QuickDraw. 

QuickDraw includes only the graphics and utility procedures and 
functions you'll need to create graphics on the screen. Keyboard 
input, mouse input, and larger user-interface constructs such as 
wi ndgws and menus are implemented In separate packages that use 
QuickDraw but are linked in as separate units. You don't need these 
units in order to use QuickDraw; Jiowever, you'll probably want to get 
the documentation for ^gach of the above ]? and learn how to use them with 
your Macintosh programs. ^ 
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ABOUT THIS MANUAL 



<*- — -^ \-\$0J 

fc-fajnllXiHpwith programming in.Pascal and 



We assume that you are i ___ 

assembly language; this graphics package is for programmers, not end 
users. 

The manual begins by stepping back a little and looking at the 
mathematical concepts that form the foundation for QuickDraw: 
coordinate plages, points, and rectangles. The mathematics are then 
associated ^o^graphic entities that can be seen on the screen. Once 
you understand these concepts, read on about the graphic entities based 
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L)-~ 
on those conceptsQ how the mathematical world of planes and rectangles 
is translated into the physical phenomena of light and shadow. 

Then comes some discussionKhow to use some of th<» miscellaneous parts 



of QuickDraw, such as using mtiltipYD graphics ports - at qncfr ; and 
manipulating character fonts. Following this discussion is a summary 
of the basic drawing process. This tells you how to structure your 
programs so that everything happens in the right order and in the right 
way. This is a particularly important section: it's got a lot of 
helpful hints on how to build programs that work right the first time. 








Finally, there's the detailed, blow-by-blow description of every 
QuickDraw procedure and function, their param eters, calling protocol, 
effects, side effects, etc^^fall the buoin a -ffc ' that you'll T^ fcir to an y>^ 
time you write a program for Macintosh. It's a lengthy section, 
because there are a lot of QuickDraw calls. But the calls and the 
parameters are summarized in an appendix for quick reference once. j) 
you've learned what they do. Q-^~"^ 

\_ oV u\ 

THE MATHEMATICAL FOUNDATION OF QUICKDRAW \V^ 

To create graphics that are both precise and pretty requires not 
supercharged features but a firm mathematical foundation for the 
features you have. If the mathematics that underlie a graphics package 
are imprecise or fuzzy, the graphics will be, too. QuickDraw defines 
some clear mathematical constructs that are widely used in its 
procedures, functions, and data types: the coordinate plane , the 
point , the rectangle , and the region . , ,. > 

The Coordinate Plane^= —j-— — 

All information about (ggn 1 1 i i tu^ location, placement] or movement -that 
you give to QuickDraw is in terms of coordinates on a plane. The 
coordinate plane is a two-dimensional grid: 
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THE MATHEMATICAL FOUNDATION OF QUICKDRAW 7 
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There are two distinct 

- All grid coordin. 

- All grid lines ai 

These concepts are im 
plane is finite, not 
coordinates range frot 
from -32768 to +32767 
maps real Cartesian s 
QuickDraw's (£6) intege 

Second, they mean tha 
are mathematically pu 
arithmetic will produ 
mind that coordinates 
concepts), you'll nev 
results from not know 
or not. 

Points 


Figure 2. Coordinate Plane 

tive features of the QuickDraw coordinate plane: 

ites are Integers; and 

re infinitely thin. 

portant! First, they mean that the QuickDraw 
infinite (although it is very large). Horizontal 
n -32768 to +32767, and vertical coordinates range 
also. (An auxiliary package is available that 
pace, with X, Y, and Z coordinates, onto 
c coordinate system.) 




t all elements represented on the coordinate, plane 
re. Mathematical calculations using integer 
ce intuitively correct results. If you keep In 
are infinitely thin (and a couple more related 
er have "endpoint paranoia" --the confusion that 
Ing whether that last dot is included in the line 




On the coordinate plane are 4,294,967,296 unique points; each point is 
at the intersection of a horizontal grid line and a vertical grid line 
As the grid lines are infinitely thin, a point is infinitely small. 
course there are more points on this grid than there are dots on the 
Macintosh screen: when using QuickDraw you associate small parts of ; 
this grid with areas on the screen, so that you aren't bound into an 
arbitrary, limited coordinate system. 

The coordinate origin (0,0) is in the middle of the grid. Horizontal 
coordinates increase as you move left to right, and vertical 
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w ■ 

2 


QuickDraw Programmer's Guide • 15 February 1982 


Page 0008 of 0064 4 



t > 
Apple Macintosh Early Technical Information • Inside Macintosh 


8 QuickDraw Programmer's Guide 

coordinates increase as you move top to bottom. This is the way both a 
TV screen and a page of English text are scanned: from the top left to 
the bottom right. 

You can store the coordinates of a point into a Pascal variable whose 
Type L defined by QuickDraw. The type Point is a record of two 
integers, and has this structure: ^^ _> 

^'^H 7F5int '= RECORD CASE INTEGER OF 

"■"•^J'^P $• < v : INTEGER; 
>J-/-*S P h : INTEGER); 

mT,^ 1- (vh: ARRAY[VHSelect] OF INTEGER) ; 

The W variantlallows you to access the vertical and horizontal 
' comports of a ?oint either individually or as an array. For example, 
if the variable *****«- were declared to be of type Point, the 
references £eM€S . 

P«*»i*.vh[v] B«ri*.vh[hl 
would all "refer to the coordinate fcrts of the point. 


y 


Ai 
r 
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w two points can define the top left and bottom Ligl.L coiutu u 
ictangle. As these points are infinitely small, the borders of 
ectangle are infinitely thin. 
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Figure 3. A Rectangle 
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THE MATHEMATICAL FOUNDATION OF QUICKDRAW 
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Rectangles arelused to define ^£ tive N > fareas on the screen, to assign 



irel u 
coordinate sypfiems to graphic entitles, and to specify the locations 
and sizes forC various, drawing commands^/ All these uses of rectangles 
are described in the section "Graphid^p Operations on Rectangles". 
QuickDraw also allows you to perform many mathematical calculations on 
rectangles: changing their sizes, shifting them around, etc. 

( hand) 

Remember that rectangles, like points, are mathematical 
concepts that have no direct representation on the 
screen. The association between these conceptual 
elements and their physical representations is made by a 
bitMap, described below. 

The data type for rectangles is called the Rect, and consists of four 
integers or two points: 



TYpe.^ 



ect = RECORD CASE INTEGER OF 



: (top : INTEGER; 

left : INTEGER; 

bottom: INTEGER; 

right : INTEGER); 

1 : (topLeft : Point; 

botRight: Point) 

END; 

Once again, the record variant allows you to access a variable of type 
Rect either as four coordinate boundaries or as two diagonally opposing ., 

corner points. Combined with the record variants for points, all of ^.i*" 1 "'* 
the following references to the Rect named Train are legal: v fl*- l " 

Train ju/ect fjjpe, ] ^£fr 

Train. topLeft Train. botRight £u/oint tyf*- j 

Train. top Train. lef t, . SuINTEGER "fyf*- I 

Train. topLeft. v Train. topLeft. h >u INTEGER < t 

Train. topLeft .vh[v] Train. topLeft. vh[h] INTEGER ., 

Train. bottom Train. right INTEGER 

Train. botRight. v . Train. botRight .h INTEGER ' . 

Train. botRight .vh[v] Train. botRight. vh[h] INTEGER 



( eye) 



If the bottom coordinate of a rectangle is riot greater 
than the top, or the right coordinate is not greater than 
the left, then the rectangle is not a rectangle. All 
operations that use that rectangle will have no effect 
whatsoever. 
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Regions 



CI 



Unlike most graphics packages that can manipulate only simple geometric 
structures (usually rectilinear, at that), Qu ickDraw has the uni que and 
amazing ability to gather an arbitrary set of ^pgrTally coh er|nP>oo-Ints 
into a structure called a region, and perform complex yeu tapid 
manipulations and calculations on such structures. This remarkable 
£eature^wi^ )flof onl y^make your standard programs simpler and faster, 
but will let you perform opierations that would otherwise be nearly" 
impossible; it is fundamental to the Macintosh user interface 



<A r 



You define a region byCd^rawing 



rectangles, ovals, 
v rounded-corner rectanglel^or/fother^ VegioniA The outline of a region 
aS^afttheSatlc ally, jeflne^as otae or more ciose d _ loops . A region can be 
co ncave or convex , can consist\pf one areaXor many disjoint areas, and 
can even have 'holes" in the raiffdle. 
I _ // ^^ 





Figure 4. Regions 



tv' 




^AJJ^ 



Because a region can be any arbitrary area^on the coordinate plane, it 
takes a variable amount of information to store the outline of a 
region. The data structure for a region, therefore, is a 
variable-length entity with two fixed fields at the beginning, followed 
by a variable-length data field: 






■fSPP Xegion = RECORD^ 

' ^RgnSize : INTEGER; 

"\tfgnBBox : Rect; 
U/ {optional region definition data} 
END; 

The^gnSize field contains the size, in bytes, of the (region variable^ 
The I<gnBBox field is a rectangle which completely encloses the region. 
For example, if the variable Lumbar is a region, then the field 
Lumbar. RgnBBox. top contains the minimum vertical coordinate of all 
points in the region. 
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The sinplest region is a rectangle; in this case, the rgnBBox field * '" \ 
serves Lo define the entire region, and there is no optional region '0^° X 4- 

data. For rectangular regions (or empty regions), the rgnSize field / > 
contains 10.) ....i f % 






As regions are of variable size, they are stored dynamically on the 
heap, and the Memory Manager moves them around as their sizes change. 
Being dynamic, a region can be accessed only through a pointer; but 
when a region is moved, all pointers referring to it must be updated. 
For this reason, all regions are accessed through handles , which point 
to one raster pointer which in turn points to the region. 

*t H?^ ,RgnPtr = "Region; 
RgnHandle = "RgnPtr; 

When the Memory Manager relocates a region's data in memory, it updates -J^ffirt/ 
only theXs nPtr master pointer to that region. The references through ^J^^r^ 
the master pointer can find the region's new home, but those references ^[-\t/^' 
that pointed directly to the region's previous position in memory now ^J ^ \P\,i^ 
point at dead bits. To access individual fields of a region, use the 
region handle anjj^double indirection: 

'Pvi ^j--~(Stevejjr .rgnSize Size of region whose handle is Steve 
£ ^r~~ Steve " . rgnBBox Boundary box of same region 

Steve^. rgnBBox Syntactically incorrect; will not compile 

If Steve is a rgnHandle 

Regions are created by a QuickDraw function which allocates space for 
the region, creates a master pointer, and returns a RgnHandle. When 
you're done with a region you can dispose of it with another QuickDraw 
call, which frees up the space used by the region. Only these calls 
allocate or deallocate regions; DO NOT use the Pascal procedure NEW to 
create a new region!/"/^ . 

Many calculations can be performed on regions. A region can be "gasfi&jn" 
or "shrunk"/-^ an<L«given any two regions^ QuickDraw can find their union, l' 

IntersectionV~trfrference, and exclusive-OR; it can also determine -7 \\)i 

whether a given point or rectangle J.ntersects a given region, etc^_ t % [L ' c\^ 




tf 



There <fs) of course a set of graphical) operations- on regions to^ draw or 
"outline "^hem on the screen^ QJ ^ j^ >^ (-fctsv-^ f*-*" 1 ^ ^ *-*-*- '"" ■' '<■ ** ■■/{■// 

The outline of a region is (Specified orlginallyjS y^raphi 
operations, which are described in the section Pen and Drawing^ 

Procedures'^^ $ WJ [^Ui^U^ 



-") 



C »J%+L~*) J ^J^^ZJS 






GRAPHIC OBJECTS /f-^ 

Coordinate planes, points, rectarigles, and regions are all good 
mathematical models, but they aren't really graphic elements-'they 
don't have a direct physical appearance. Some graphic entities that do 
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/I 



have a direct graphic interpretation are the bit image , pattern , 
cursor, and bitMap. This section describes the data structure of these 
graphic entities and how they relate to the mathematical constructs 
described above. The next section begins to describe the graphic 
operations that you can perform with QuickDraw to draw pictures. 



The Bit Image . 

A bit image is a collection of bits in memory which have a rectiline'ar>^/ 
representation. Take a collection of words' in memory and lay them end 
to end so that bit 15 of the lowest-numbered word is on the left and 




on the far 



Then take this 



bit of the highest-numbered word 
array of bits and divide it, ombytl^ boundaries, into a number of 
equal-size rows. Stack these rows vertically so that the first row is 
on top and the last row is on bottom. 



First 

Bute 



iiins^:: 
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Figure 5. A Bit Image 

The result is a matrix like the above- -rows and columns of bits, with 
each row containing the same number of bytes. The number of byte s in 
each row of the bit image is called the row width of that image. 

A bit image can be stored in any static or dynamic variable, and can be 
of any length that is a multiple of the row width. q- •?/\d. 

The Macintosh screen Itself is one large vlsibleb^-jgage. The upper 
Hii ?]<J >.yi-<»b of memory is displayed as a matrix o^^^^^^wpixels" on the 
scr<£gfiii5 each bit corresponding to one pixel. Ir^a— Wrt's value is 0, 
its pixel is white; if the bit's value is 1, the pixel is black. 

£ — 1 / f""~7 

The screen 1 rl ftfifiYpi-A'l t tall andl 3jlijj pixels wide, and the row width of 
its bit image lsC^S/bytes. Each pixelon the screen is square; the 
('aspect ratio i>f the display is 3:2/(h:v)j. ? 



3L' 
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( hand) 



As each pixel on the screen represents one bit In a b 
image, whenever this document says "bit", you can 



Patterns 



substitute "pixel".. , (A, 5 . <\ 'A \iX 



A pattern is a 64-bit imagexorga. 
is used to define a repeating 
used to draw with, to fill an a 
bitwise operation. J^ 



nized as an/8 
ge or ton^ktjn 




vrf 



by-8-bit square, which 
Patterns can 'be 
the source for a 




Patt erns are dr awn aligned* 

£t«^!*i£35£i«g adjacint ml . a feg l a p pin g areas w^*P_the_ same patter 
EEfldagom -a -continuous , coordinated pattern^ QuickDraw provides^ > 5 p 1 ^ 
predefined patterns for White, Black, Gray, LtGray, and DkGray. Any 
other 64-bit variable or constant can be used as a pattern, too. The 
data type definition for a pattern is as follows: 

-fW£ Pattern = PACKED ARRAY[0..7] OF 0.-255 

The row width of a pattern is 1 byte. 




ft 



The VbjitMap 



1 



<* 



\ftA^ 



^ V 



When you combine the physical [entity of a bit image with the conceptual 
entities of the coordinate <grid) and rectangle, you get a bitMap. A 
bitMap is a\d_e_scr'iptor*'that has three parts: a pointer to a bit image , 
the r ow wid , ^ hfin bytes) of that image, and a( bound^^ -r^ctangle which 
gives^tihe bitfigj^fr oth its dimensions and a coordinate system. Notice 
that a* ul tfTtMap", as we will use the term, does not actually include the 
bits themselves: a bitMap is a descriptor containing a pointer to a 
bit image. 

Because a bitMap points to a bit image, there can be several bitMaps 
extant simultaneously that all impose different coordinate systems on 
the same bit image. This important feature is explained more fully in 
"Coordinates in grafPorts", below. 






^Mt 
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Btl St? ^ife 

Address 





V 



Figure 6. A bitMap 
The data structure of a bitMap follows: 



/^ 




bitMap = RECORD 

baseAddr :' Wo rdPt 
rowBytes : INTEGER; 
bounds : Rect 
END* 

The baseAddr field is a pointer to the beginning of the bit image in 
memory, and the rowBytes field is the number of bytes in each row of 
the image. Both of these should always be even: a bitMap should 
always begin on a word boundary, and contain an integral number of 
words in each row. 

The bounds field is a boundfc^fcyjrejt angle ) that both encloses the(J§ictiv£ 
area of the bit image and imposes\a coordinate system upon it. 
relationship of the bound^jjj rectangle and bit image in a bitMap is 
simple yet very important. First, a few general rules: 




- Bits in a 



i#><H& 



fell between points on the coordinate 



M 



^P 






- A rectangle divides a bit image into two sets of bits: 
inside the rectangle and those outside the rectangle. 



those bits 



- A rectangle that is H points wide and V points tall encloses 
exaetly/"( H*V)) bits. _ / ^. , ) + (\J. | ) 

The topl eft com ar of the bounding rectangle is aligned around the 
f irst^bj^£Iin_^hebi«|gf) The width of the rectangle determines how 
many bits of~one row are logically owned by the bitMap; the 
relationship / 



-{■WO 






\ I 
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Map.rowBytes >= ©(Map. bounds .right-Map. bounds. left) 



must always be true. The height of the rectangle determines how many 
rows of the image are logically owned by the bitMap; the relationship 



SIZEOF(Map.baseAddr~) >= (Map. bounds .bottom-MapibOiinds .top) 

* Map.rowBytes 

must always be true to ensure that the number of bits in the logical 
bitMap area is not larger than the number of bits in the bit image. 



-no- 






jp 






J 



Normally, the bounds»gj rectangle completely encloses the bit image: 
the width of the boundfifcg! rectangle is equal to the number of bits in 
one row of the image, and the height of the rectangle is equal to the 
number of rows in the image. If the rectangle is smaller than the 
dimensions of the image, the least significant bits in each row, as 
well as the last rows in the image, are not affected by any operations 
on the bitMap. . t {? \ 

The^&A-t-Map al^o imposes a coordinate system on the image. Because bits 
fall between coordinate points, the coordinate system assigns integer 
values to the lines tha^t^Jjoj^dgj^jand^gjiarate-b- it s, n e- t-to tire — bXt____ 
positions themselves. fjf~a bitMapis assigned the bounding rectangle 
(10, -J) (31,-1) (10,8) (3*,8), the bottom right bit in the image will 



-ft 1 

5 



y^ 

qe 



\cns jL4-tlA~-h){<- 






be between J horizontal coordinates 34 and 31, and between vertical 
linatefe 7 and 8. \ b( 



\ 




X, 



i/r\ </ 



drp 



f 

'A 1 



S 



> * 



V 



i 
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Figure 7. Coordinates and bitMaps 
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Cursors 



A cursor is a small V^magej that appears on the screen and is controlled 
by the mouse. Cursors are defined as a 256-bit image, a 16-by-16— / ^£ 
square. The row width of a cursor is 2 bytes. 








-8 



8 8 

Figure 8. Cursors 



A cursor has three fields: a 16-word data field that contains the 
image itself, a 16-word mask fie lji that con tains information about the 
screen appearance of each bitf^ofth e cursoj ^ and^a "hotSpo t" point that 



aligns the cursor with the posTTTon of the\mouse. 



lA^r 



,15] OF/INTEGER; 
.15] OF INTEGER; 






^< 



^u *tf 



+0J^ 



<V 



*v 



cv 



4- 



Cursor = RECORD 

data = ARRAY[0 
mask = ARRA?[0 
hotSpot = Point 
END' 

The data for the cursor must begin on a word boundary 

The cursor^ appears on the screen as a 16-by-16-bit square. ^ Each bit of 
the squarejis Wa ntrolle <j- by two corresponding bits in the data and > ,, 

maskH^/tf^. // -fidL- wjf£M> & <f,<h -ffa- pfftL t^*<M^' '-ftvu CMAJiV (flu, ^ 



Data 


1 
t> 
1 



>1 

f The hot gpot aligns 
\ the mouse position 



A 



1 Bda wL in am jiwu.uuuaKG ^lite 

1 PAjtoli tti ' mu i Wttp ' p ' Uai.J fl Lack 

^W'ixel under cursor 
0^ wA «,^ixel under cursq 

a point in oheHnage (iwx a bit, a point!) 





with 






Imagine the rectangle with corners (0,0) and 



raming the Imagejf the hotSpot is defined In this coordinate 
systeni. A hotSpot of (0,0) is at the top left of the Image,;^ $ hotSpot 
of (iyg) is in the exact center of the image .^ Vnienev^x^you move the 



V 
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mouse, the low-level interrupt-driven mouse routines move the cursor's 
hot spot to be aligned with the new mouse position. 



( hand) 



The mouse position is always, unalterably linked to the 
cursor position. You can't reposition the cursor through 
software: the only control you have is whether it is 
visible or not, and what shape it will assume. Think of 
it as being hard-wired: if the cursor is visible, it 
always follows the mouse over the full size of the 
screen. 



QuickDraw supplies one predefined cvirsor, a pointing arrow, named 
Arrow. 



The lekaf Port 



A grafPort is a complete drawing environment that defines how and where 
graphic operations will have their effect. A grafPort is like a 
logical output device: it contains all the information about one 
instance of graphic output that is kept separate from all other 
instances- You can have many graf Ports open at once, and each one will J 
have its own coordinate system, drawing pattern, background pattern, />-*/ 
pen size and location, character font, size, and style, and bitMap inftoj 
which drawing takes place; one statement will instantly switch you from 
one port to another. Graf Ports are the structures on which we build 
windows, which are fundamental to the Macintosh "overlapping folders" 
user interface. 



A grafPort is a dynamic data structure with ten fields: 

-y\fa ^rafPtr = grafPort; 

grafPort = RECORD 
~ portBits 



portRect 

visRgn 

clipRgn 

bkPat 

chStyle 

pnLoc 

pnSize 

pnMode 

pnPat 



^itMap; (Ml " 

Rect; Ia-4W ^ ?>^i-<5p 






^RgnHandle; (^icuxEi" ft po^Mx) 



RgnHandle; 
: Pattern^ 
MCharStyle 

Point; 

INTEGER; 

Pattern 




END' 
) 



All QuickDraw operations refer to graf Ports via grafPtrs. You create a 
grafPort with the Pascal procedure NEW and use the resultant pointer in 
calls to QuickDraw. You could, of course, declare a static VAR of type 
grafPort, and obtain a .pointer to that static structure (with the @ 
operator), but as most/ grafPorts will be used dynamically, their data 
structures should be dynamic also. 



(^ 
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( hand) *; 

You can access all fields and sub-)fields of a grafPort 
normally, but you should not store new values directly 
into them. Qu ickDraw has proced ur es for altering all 
f ields of a grafPort. and using these procedures ensures 
that changing a grafPort produces no unusual side 
effects. 



h 



-i\ 



.<A 






% 



The portBits field of a grafPort is the bitMap that points to the bit 
image in memory to be used by the grafPort. All drawing that is done 
in this grafPort will take place in this bit image. i/The default bitMap 
uses thefffi^intosh video screen as its bit Inage, iti** 1 a rowBytes of 48 
and hM a bounda^" rectangle of (0,0) (38*4, 256). The bitMap can be 
changed to indicate a different structure in memory: all graphics 
procedures work in exactly the same fashion regardless of whether their 
effects are visible on the screen. A program can, for example, prepare 
an image to be printed on a printer without ever displaying the image 
on the screen; or a picture can be developed in an off-screen bitmap 
before being transferred whole to the screen. The coordinate system of 
the grafPort can be changed by altering the coordinates of the 
portBits. bounds rectangle; with a QuickDraw procedure call, you can set 
^arbitrary coordinate systemT for each grafPort, even if they all use 
the same bit image (i.e. Athe^screen) . -f^c ^HW Lt -^ 

The portRect field is a rectangle that defines a subset of the bitMap 
for use by the grafPort. Its. coordinates are in the system defined by 
the portBit bitMap' s boundt&g rectangle. All drawing done by the user 
or application program is clipped to the inside of this rectangle; the 
portRect usually defines the "writable" interior area of a folder, 
document, or other object on the screen. 

The visRgn field is manipulated by the Window Manager; users and 
programmers will normally never change a grafPort's visRgn. It 
indicates that region (remember, an arbitrary area or set of areas) 
ttfiPis actually visible on the screen. For example, if you move one 
folder on top of another, the Window Manager (loglcaly^ removes the area 
of overlap from the visRgn of the folder on bottom. When you draw into 
the bottom folder, whatever's being drawn is clipped to the visRgn so 
that it doesn't run over onto the top folder. The default visRgn is 
set to the portRect. 



^ 




ws 



0^ 



o~> 




o^ 



ll+t*^^ 



V 



V V 



2/17/82 Espinosa 



/QUICK. DRAW/QUIKDRAW . 3 



QuickDraw Programmer's Guide • 15 February 1982 



Page 001 9 of 0064 



Apple Macintosh Early Technical Information • Inside Macintosh 



GRAPHIC OBJECTS 



19 • 














«1 
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1 







Figure 9. grafPort Regions 

The clipRgn is an arbitrary region that you can use to limit drawing to 
any Tegion within the portRect. If, for example, you want to draw a 
half circle on the screen, you can set the clipping region to half the 
square that would enclose the whole circle, and go ahead and draw the 
whole circle. Only the half within the clipRgn will actually be drawn 
in the grafPort. The default clipping region is set arbitrarily large, 
and you have full control over its setting. . c . f, n t~r, ' yLx 



'ilwiM l*& 



•t Uv 




The bkPat is a pattern that is used/ for filling in the background of a ^—, 
picture during erasing or scrolling}. This pattern, like all other ^ \ 



patterns, is always drawn aligned with the local coordinates of the 
grafPort. 



\3 



The chStyle is a record (see below) that determines the font and style 
of characters drawn in the grafPort. 

The last four fields deal with the graphics pen. Each grafPort has one 
^ and only one graphics pen, which is used for drawing lines and printing 
text. The pen has four characteristics: a location, a size, a drawing 
mode, and a drawing pattern. 
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^eSe.'oi^I' 

Q|)E!BGQ|D r 
DeJEjEj|l r 




Figure 10. A Graphics Pen 



\ 



The pen location is a point in the local coordinate system of the 
grafPort (see helow) . The pen location can be anywhere on the 
coordinate plane: there are no restrictions on the movement or 
placement of the pen. Remember that Jthe^pen location is aj>oint on the 
coordinate plane, not a pixel in a (bitMajpl^ dji'-t" M*-^ 



. (bitMap I 



tit on tne n 



er-4efi 



The pen is rectangular in shape, and hj|JL-a user-definable width and 
height. The default size is a l-by-l-^i'fuare; the width and height can 
range from (0,0). to (32767,32767). If either the pen width or the pen 
height jmm less than i, ^however, the pen will riot draw on the screen. 

- The peiv appears- as a rectangle with its a.ppift&-left corner at the 
pen location; it hangs below and to the right of the pen location. 

The pnMode and pnPat fields of a gra fPort determine how t hose bits 
under the pen are affected^ — The - " prifat is a pattern that is used like 
the "ink" in the pen. The" pattern is drawn on the bitMap aliened with, 
the local coordinate system of the grafPort, so that drawing adjacent 
or overlapping areas in the same pattern produces a continuous, 
coordinated pattern. Five patterns are predefined (white, black, and 
three shades of gray) ; you can create your own t onal or repeating 
pattern and use it as the pnPat. (A utility procedure, called 
StuffHex, allows you to fill patterns easily.) 

The pnMode field determines how the pen pattern is to affect what's 
already on the bitMap. When the pen draws, QuickDraw first determines 
what bits of the bitMap will be affected, and finds their corresponding 
bits in the pattern. It then does a bit-by-bit evaluation based on the 
pen mode, which specifies one of eight boolean operations to perform. 
The resulting bit is placed into its proper place in the bitMap. The 
pen modes are discussed in "Transfer Modes", below. 



v/ 
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The following graphics procedures use the pnSize when drawing: 



LineTo 

FrameRect 

FrameRoundRect 



Line 
FrameOval 

FraaeRgn 



These procedures, as well as the ones above, also use the pnMode and 
pnPat when drawing: 



PaintRect 
PaintRoundRect 



PaintOval 
PaintRgn 



COORDINATES IN GRAFPORTS 



Each grafPort has its own local coordinate system. All fields in the 
grafPort are expressed in these coordinates, and all calculations and 
actions performed in QuickDraw use the local coordinate system of the 
currently selected port. 



Two things are important to remember: 



tst^ 



- Each grafPort maps a portion of a coordinate gar4A> into a 
similarly-sized portion of a bit image. 

- The portBits. bounds field defines the local coordinates for a 
grafPort. 



* 



< 







The interrelationship between the portBits. bounds and portRect^ 
.. rectangles is very import an£ J y'~E5lgfe» *fiie top left corner of 
po r tBi t s . boun d s_is always al igned ar ound the fir st b;Lt in the bit 
fmage~]~ the coordinates of thatf corner "anchor" a point on the grid to 
t"h"at~pixel in the bit image. This forms a common reference point for 
multiple graf Ports using the same bit image (such as the screen); given 
a portBits. bounds rectangle for each port, you know that their top left 
corners coincide. 

As the portBits. bounds rectangle establishes a coordinate system for ( ]fL, 

the port, the portRect rectangle indicates the section of the 

coordinate ^SS^tand thus the bit image) < fwill be~usedAf or drawing. The . 
portRect usually falls inside the portBits. bounds rectangle, but it is 
not required to do so. <e^^H^V**d, 

When a new gr-aTra^ls created and initialized, ics bitMap is Bet to 
point to the [Macintosh screen, and both the portBits. bounds and the 
portRect rectangles are set to 384-by-256irectangles, with the origin 
point (0,0) at the top left corner of the screenT^N ^ /> 

Youfr (Toc1a o rigin pointy oTThe grafPort is alway gJthe top left 

of the portESct." YdlPcai 

procedure; this recalculates/all coordinate 



f^. . N 
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be relative to the new origin point. For example, calling the 
procedure . 



\y 
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Figure 11. Setting Local Coordinates \ ,^' 

will recalculate the coordinate components of these elements: 
Oakland". portBits. bounds Oakland". portRect , 

Oakland" .visRgn 

All of the above items are always "in sync", so to speak: all 
calculations, comparisons, or operations that seem right, work right. 

Notice that when the local coordinates of a grafPort are offset the 
visRgn of that port is offset also, but thsjiiBSffiLiS-ML. A good way 
to think of it Is that if a document is being shown Jj" 1 ^ J,J rafPort ' 
the document "sticks" to the coordinate system^nd the port s 
structure "sticks" to the f screen r sr roll in, a f ^ent u jwarcT nside 
IrV DorTTinvolves keeping all the do c mpnt's stuffJ dik g.tlH' rllpRRnf 

at \E sJZhvMP*** a11 the P ° rt ' S stu "J like " 8 >I-T he top 
^rtBits.boun^tRect, and visRgn) is move downwards. U the top 



at the same g Sttj^ frhlg all the port's stuff (like its _ _ -- 
SrtBitB.bouSrTpTrtRect, and visRgn) is moved downwards. U the top 
Jeft corner of portBits. bounds^ -fixed, moving its gdinates 4°™ 
looks like you're moving the/doujient up>^-_ , ^ u ^ tU ^ \+ £ ^^X 



( band) ^ t ^ eg pia<;e ^^^ a grafPort and uses the 

local coordinates of that grafPort. If you are moving, 
comparing, or otherwise dealing with mathematical items 
in different graf Ports (for example, finding the 
intersection of two regions in two different graf Ports), 
you must adjust to a common coordinate system before you 
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LMv 

e bitMap will be affected, 



QuickDraw first determines what bits of t 
and dues a bit-by-bit comparison based on/ the mode (described in 
"Transfer Modes'" , below) . The^xe sultan t kits are stored into the 
bitMap __ „ 



( hand) 



The character drawing modet^should bepfestricted to either 
srcOr, srcXor, or srcBic in erdeftoimake kerned 
characters not obliterate each other. 




<7 *<£&> 



<* 



H 




The_next four fields control the appearance of the font: 
Utalici4lngV>letterspacing, and shadowing. You can apply these either 
alone" or in combination; however, combinations of modes usually look 
good only for large fonts. All parameters should be positive; never 
set any of these parameters less than zero! 



J 



•^ Normal Characters 

^^Q \ Italic characters 

Widened iroRc characters 










V 



Figure 12. Character Styles ■= 

The bold parameter controls linear overstriking of characters: the 
character is repeatedly "printed" one bit to the right^the number of 
times specified by the bold field. 

The slant parameter adds an italic slant to the characters. A slant of 
produces characters whose verticals are perpendicular to the 
baseline; a slant of 8 produces a nice amount of italicizing for a 
10-point font. The number of dots of horizontal skew per vertical line 
is determined by this formula: 



skewdots := 



slant 
16 



Character bits above the baseline are skewed right; bits below the 
baseline are skewed left. 
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CHARACTER FONTS 



aL 



25 



A' 



F 



J 



V 



d 



The extra parameter adds space after the character; the HupiiiuI extr 
space is 0. You can ndd extra space in order to. lotfaog B paeo ■— 
Mini inwli ii ii ; it's also helpful to add extra space <4>mi^fw um i h a l i i ii n' ^or 
shadow*Ttiaracters. J 1 ^* slanted characters are kerned, it's not 
necessary to give them extra space. 

Character sWadowing, controlled by the shadow parameter, is like 
ag | 1iri1 H>«<wp but .makes a hollow, outlined character rather than a solid 
one. Like a ^jola^ff ^g^theshadow parameter controls the number of ■ 
times the character is-CoVerstruck" ; reasonable values are 0, 1, 2, and 
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GENERAL DISCUSSION OF DRAWING 



Drawing occurs: ~ 

- Always inside of a grafPort, with the port's coordinate system; 

- Usually with the grafPort' s pen (that is, pen location, size, and . 
pattern); 

- On the grafPort's bitMap; and 

- Always clipped to the intersection of the (portRect, /bitMap bounds, \ 
visible region, and clipping region. 

.Three things can be drawn: lines, shapes, and characters. Shapes 
include rectangles, ovals, rounded-corner rectangles, and regions, all/ 
either/ 'solid*) or framed (hollow) . 

^ines are defined by two points: the current pen location— and a 
destination location. When drawing a line, Qu i ckDr a^d raws^t net o p 
left corner of the pen along the mathematical trajecto-ry^Trom the" 
current location to the destination. The pen hangs below and to the 
right of the trajectory. 
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Figure 13. Drawing Lines 



( hand) 



l/rt 



-tk i± 



I- 



r 



..-.A " 



No mathematical element (such as the pen location) is 
ever affected by clipping; clipping only determines what 
appears whered^ ffip^^ ls^WS ^ you draw a line to a 
location outside of your grafPort, the pen location will 
t rjm aXIP )there ; but only the portion of the line that is 
inside the pott will actually be drawn. This is true for 
all drawing procedures. 



Simple shapes (rectangles, ovals, and rounded -corner rectangles) are 
defined by two corner points. The shapes always appear inside the 
mathematical rectangle defined by the two points. A region is defined 
in a more complex manner, but it too appears only within the rectangle 
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Figure 14. 

In the case of framed shapes, the outline still appears within the 
defining rectangle, and the vertical and horizontal thickness of the 
outline is determined by the pen size: 




Figure 15. Drawing Framed Shapes 

The pen pattern is used to fill in the bits that are affected by they 
drawing operation. The pen mode defines how those bits are to be 
affected by directing QuickDraw to apply one of eight boolean 
operations to the bits in the shape and the corresponding fbitsfon the 
screen.) 

ter drawing does not use the pnMode or pnPati but it does use the 

Char_ac-ter.s are placed to the rigtrt Trf the current pen location, 

their baselines at the pen vertical location, and the pen is moved 
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QuickDraw rrattdaiiucr's Guide 



/^rt/tx^i fid. u i . i-L. 

to the right a distance equal to the width of the character. / No wrap 
or carriage return is performed automatically. 

The method QuickDraw uses in placing characters is controlled by a mode 
parameter similar to the pen mode. This pars 
"Transfer Modes", below. Clipping of charact 
exactly the same manner as all other clipping 

Transfer Modes / I \ 

Vhrn i^ ra^jjc -^ Lt i ijiif i . w irh-Tpiiii | nr ri Tiol ii n i w l " the pnMode (op "AhOfay ii 

field determines how the drawing is to appear on the screen! Fo 
bit in the item to be drawn, QuickDr^w-iinc?s_the corresponding hi 
the bit image»a«ri- performs one of/sixteen/Loolean trnunfij intuition 
the pair of bits, and stores the reVul t"fng bit into the bit image 

There are four basic operations: Copy, OR, XOR, and BIC. Each 
these has a variant in which the drawing bit is inverted before the 
operation is performed, giving eight operations. These eight are used 





IV 



iX draw ing with a pattern; ther e are another eight f or trans fer^ng one 
lit TmagS ^onto another, giving ^ Ixteen operations in atl^ Each mode is 
defined by name as a constant in QuickDraw. ~~ — 



Transferring-^ Source Bit Image (XferRect, XferRgn), 

\\\ J\ 'TrMAP/O \ ( Actionjfor each bit in source: ^ 

j£\^ 5 Model 




l W 




srcCopy 
srcOr 
srcXor 
srcBic 

notSrcCopy 
notSrcOr 
notSrcXor 
notSrcBic 



"Paint" 
"Overlay" 
'Invert" 
"Erase" 

"Paint" 
"Overlay" 
'Invert" 
"Erase" 



Force Black 
\Force Black 
[nvert 
>rce White 

Fbrce Black 
leave Alone 
■Leave Alone 
Leave Alone 



Force White 
Leave Alone 
Leave Alone 
Leave Alone 

Force White~ 
Force White 
Invert 
Force White 




Transferring a Pattern (Line, LineTo, Paint 



Models' 






Action/for each bit in pattern 



patCopy 
patOr 
patXor 
patBic 



\$lack : r 

"Paint" / Fore " 
"Overlay" Force Black 
"Inver^r Invert 
"Eraser Force White 



White : 

Leave Alone 
Leave Alone 
Leave Alone 




-k-Hr^ 



notPatCopy "Paintj" Force Black Force White 

notPatOr "Overlay" Leave Alone Force White 

oiotPatXor " Invar t" Leave Alone Invert 

nptPatBic "Erase" Leave Alone Force White 

The pnMode parameter must be one of the patternfmodes; the chStyle.mode 
parameter must be one of the soutee. modes. 

I \ 

: +* 
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DESCRIPTION OF QUICKDRAW PROCEDURES 



The following pages describe aae+r function and procedure in QuickDraw, 
their parameters, and their operation. They are given in their Pascal 
form; instructions on how to make procedure and function calls from 
assembly language appearOafter the calls. 



grafPort Procedures 



PROCEDURE InitGraf; 



-I 



H f 



**£. 



Call once and only once at the beginning/ of your program to initialize 
QuickDraw. It initializes the QuickDraw} global variables: 



Variable 



V 



SS; 



: ^ 



white 
black 
'"> gray 
ltGray 
dkGray 
arrow 
charNormal 
screenBits 
thePort """ 
-rgnSave-^^ 



Type 



Setting 



Pattern All-white pattern 

Pattern All-black pattern 

Pattern 50% gr 

Pattern 33% grjHy pattern 

Pattern 66% grey pattern 

Cursor JEG4ttt-4ng-.arrow cursor 

(c)iarStyle -NO FONJ^SrcOr mode, no extras 

^itMap ^Macintosh screen, (0,0,384,256) 

~£fa~f per-- — ra 

BOOLEAN JFalst 




"/■ 



/ InitGraf~aTs~o "places -the—cursor on the screen. 



PROCEDURE OpenPort (gp: 



GrafPtr); 




Initializes the selected grafPort and makes it the current port (see 
SetPort). You must perform an OpenPort before using any grafPort* To 
use OpenPort, perform a NEW to create a GrafPtr and use this GrafPtr in 
the OpenPort call. 

These default values are set by OpenPort: 



Variable 



Type 



portBits 


BitMap 


portRect 


Rect 


visRgn~~ 


Region 


clipRgn 


Region 


bkPat 


Pattern 


chStyle 


CharStyle 


pnLoc 


Point 


pnSize 


Point 


pnMode 


INTEGER 


pnPat 


Pattern 



Setting 



ScreenBits (see InitGraf) 

ScreenBits. bounds (0,0,384,256) 

Rectangular, (0,0,384,256) 

Rectangular , ( -30000 , -30000 , 30000 , 30000) 

White 

CharNormal 

(0,0) 

(1,1) v 

pat Copy T v 



Blacks 



A> 



\ 
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The top left corner of the portRect remains at its same location; the 
width of the portRect is set to width, and the height of the portRect 
is set to height. In other words, PortSize moves the bottom right 
corner of the portRect to a position relative to the top left corner. 



PortSize does not \4ipdate)the clipRgn or the visRgn, nor does it affect 
the local coordinate system of the grafPort: it only changes its width 
and height. Remember that all drawing occurs only in the intersection 
of the portRect, the portBits. bounds , the visRgn, and the clipRgn. 



PROCEDURE MovePortTo (lef tGlobal ,topGlobal: INTEGER); 

Changes the position_of the portRect In the bitMap (read_J|oii 
screen" )<5H^thoutT alter ing _ the local ~cb o r31 "n§flEe~~s" y s t em of the 
THIS DOES NOT~AFFECT THE S CR£ETrT~Tt"me rely changes the locati 
screen at which drawing inside the port will appear, q. \fof<$ gJrJ 1 -' 

( hand) 

This procedure is normally called only by the Window 
Manager . 

leftGlobal and topGlobal set the distance between the corners of 
portBits. bounds and the new portRect. For example, , j— nuf<^ 

MovePortTo(192,128); ^^~^^j\m^- l/vO-A> MAtAV -"" 

will move the top left corner of the portRect to the center of the 
screen (if portBits is the Macintosh screen) regardless of the local 
coordinate system. ^^^^^^^ 

I MovePortTo recalculates the coordinates of nnrl lUrr Tmnidrr but leave 
\^ all other coordinates unchanged. 

PROCEDURE SetOrigin (h,v: INTEGER); 

This changes the loraj , r-oardlnate system of the current grafPort. ^THIS_ 

D OES ffOT AFFECT THE "SCR EEN^ i t does, however, af fe^twhere__subsequent 

"drawing "and"" calcuTaFion Unl appear in the port^Sh the_IgcJeejy. It 



rawing and calculation Will appear in the poi 
updates the coordinates of the portRect, the portBits. bounds, and the 
visRgn. All subsequent drawing and calculation commands will use the 
new coordinate system. 

The h and v parameters set the coordinates of the top left corner of 
the portRect. All other coordina tes a x£_ calculated from this point. 
All relative distances among any ffilimentsjin the p<rrtr3iAll remain the 




Jus 



.&> 



ves J 







same; only their absolute local coor 



change. 



( hand) 



SetOrigin does not update_the_coordinates of the clipRgn 
or the pen; these items jsticktb 1 * tne document^ ins ide lihep 





\ 
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PROCEDURE SetVisRgn (rgn: RgnHandle); 

Declares the region whose handle is supplied in rgn to be the visible 
region of the current port. 

This procedure is normally called only by the Window Manager. — 

( hand) 

Note that SetVisRgn does not make a copy of the object 
region; it merely saves the RgnHandle ln» - ^ ' 
grafPort .visRgn. Thus, any subsequent changes you make 
to rgn will also affect the visible region of the port 

Be careful never to disposeC a region that has been set as the visible 
region of a grafPort^ unless you are also disposing^the grafPort 
itself. 



Y 



*■ >m^ 




PROCEDURE GetVisRgn (VAR rgn: RgnHandle); \. * ^T Vte*" 

Returns a pointer to the ctM?*«tt visible regionL » It is defined in the 
coordinate system of the grafPort; if you wish to use this region in 
another port, you must offset it (see "Coordinate Systems"). „ 



PROCEDURE SetClipRgrfi (rgn: RgnHandle); 



S> 



C/ 



{A 



Declares the region wh»se_handle is supplied in rgn to be the clipping 
• region of the current(por£* You can set the clipping region to any 
arbitrary region, to aid you in drawing inside the grafPort. The 
default clipRgn is an arbitrarily large rectangle. 



*$ 

$ 



r 



j 



( hand) 



Note that SetClipRgn does not make a copy of the object 
region; it merely saves the RgnHandle i.v(to\—e. — »- 
grafPort.clipRgn. Thus, any subsequent changes you make 
to rgn will also affect the^rlipping region of the port. 
Be careful never to dispose'va] region that has been set as 
the clipping region (Amies soyou are disposing of the 
grafPort itself^. \> 







rgn: RgnHandle); 



PROCEDURE GetCliriRgri 

Returns a handle to the clipping region of the current grafPort. You 
can use this, for example, to get a handle_to_use in a region operation 
such as XorRgn, UnionRgn,. Of fsetRgn, 

It is defined in the coordinate system of the j QrafCPorb^ if you wish to 
use this region in another port, you must offset it (see the 
LocalToGlobal and GlobalToLocal calls). 



V 
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PROCEDURE ClipRect/ (r: Rect); 



Sets }the clipping 
equivalent to the 



region of the current grafPort to a rectangle 
Irectangle r. NOTE that this does not change the 
region handle, but/yaf fectr*the region itselfj in combination wiTfi" 
SetClipRgn, this -may produce unexpected side effects. For example, 



SetClipRgn(myRegion) ; 

{ } 

ClipRect(anyRect) 



H 



Vds' 



Jt 



it/ 



will not only set the clipping region to anyRect, but will also chan; 
myRegiqn_ to anyRect. -ftx* p^JL* £ (^^ Ci^t^ t %^_ ^ 

^ r'^ ..~~zz:\. : .;._""' '-J. " " 

PROCEDURE BackPat (pat: Pattern); 




Sets the background pattern of the_current grafPort to pat. The- 
background pattern is used (in^EraseRect , EraseOval, EraseRoundRect , 
CraseRgp, and ScrollRect. V s ^ / 

^ I ^^c^ 



Cursor-Handling Procedures 



r 



PROCEDURE SetCursor (crsr: Cursor); 



P 



Sets the current cursor to the 16-by-16 / image in crsr. If the cursor 
is hidden, it remains hidden and will attain the new appearance when it 
is uncovered; if the cursor is already visible, it attains the new 
appearance immediately. 



The initial (cursor image, when a port is created, is visible on the 
screen as a/a^north-northwes t - jg jfl Oi«fojfl arrow. There is no way to 
retrieve the current cursor image. 




■k. 



■1 



/0Tc/x.9*ef* e6f [ 



PROCEDURE HideCursor; 



•iK 



'sry^ t> 






,V> -' 



Removes the cursor from the screen, restoring the bits under it. 

HideCursor also decrements a "cursor-level" variable, which keeps track^- i^ 

of the number of times the cursor has been hidden to compensate for t\ c V" p> 

nested calls to HideCursor and ShowCursor. Every call to HideCursor 

should_be_bn1nnrpd by— a~ .auksjaguent call to ShowCur so r . At 

initialization, the cursor Is not hidden. j{\*&~ '^ rJV^ 



w? vb&jiZv 



PROCEDURE ShowCursor; 




Increments the "cursor-level" variable^and, if the level 
i^os itlv^ , displays the cursor on the screen. The level 
'so extra calls to ShowCursor don't hurt. Each call to Show 
should balance a previous call to HideCursor. 



1JJUJ , 
l/Xl/Sl Espinosa 
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QuickDraw low-level inter rupt-driven routines link the cursor with the 
mouse po&Ition, so that if the cursor level is (visible), the cursor 
automatically follows the mouse. You don't need to do anything but a 
ShowCursor to have a cursor track the mouse. There is no way to 
"disconnect" the cursor from the mouse; you can't force the cursor to a 
certain position, nor can you easily prevent the cursor from entering a 
certain area of the screen. 

If the cursor has been changed (with SetCursor) while hidden, 
ShowCursor presents the new cursor. 

The initial cursor state is a north-northwest arrow, not hidden. 



PROCEDURE CursorVis (visible: BOOLEAN); 

A general-purpose cursor showing and hiding procedure: CursorVis (TRUE) 
simply calls ShowCursor, and CursorVis(FALSE) calls HideCursor. 



Pen and Drawing Procedures 



£ 



j^nv 



The pen and drawing procedures ax a all de.pc.ndi.ut upirn the coordinate 
system of the current grafPort. Remember that each grafPort has its 
own pen; if you draw in one grafPort, change to another, and return to 
the first, the pen will have remained in the same location. 




PROCEDURE PenSize (width, height : INTEGER); 
Sets the dimensions of the graphics 



nrafPort. All 



subsequent Line, LineTo , <Er ameRect . Fra meOval . _ FrameRoundRe^ts and 
FrameRgn procedure calls in the same grafPort will~use~tfce^ijew pen 
dimensions. , 

is 0/ i 

If either of the pen dim ensi ons sss- set to»nonpositive value#, the pen 
assumes the dimensions/(?7&3>and no drawing * s performed. The current 
pen dimensions can be accessed in the variable thePorf.pnSize, which 
is of type Point (it has components .h and .v) . For a discussion of 
how the pen draws, see the "General Discussion of Drawing" earlier in 
this document. 



PROCEDURE GetPen (VAR pt: Point); 

Returns the current pen location, in the local coordinates of the 
current grafPort. 



( eye) 



If the coordinate system has been changed with SetOrigin 
since the last pen motion, the pen will not be in the 
same location on the screen. The pen "st icks" t-n t hp - 
document: moving the document-J ^tglg^p sefcW^^^BteR. with 
SetOrigin carries the pen with it into a new location in 
the grafPort. It will, however, be in the same location 
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relative to the coordinates of other items. 



PROCEDURE GetPenState (VAR pnState: PenState); 

Saves the pen location, size, and pattern Into a storage variable, to 
be restored later with SetPenState (below). This is useful when 
calling short subroutines that operate in the current port but must 
change the graphics pen: each such procedure can save the pen's state 
when it's called, do whatever it needs to do, and restore the previous 
pen state immediately before returning. 

The PenState data type is not really useful for anything except saving 
the pen's state. t 



PROCEDURE SetPenState (pnState: PenState); 



Sets the pen's location, size, and" pattern in the current grafPort to 
the values stored in pnState. This is usually called at the end of a 
procedure that has altered the pen parameters and wants to restore them 
to their state at the beginning of the procedure (see GetPenState, 
above) . 



PROCEDURE PenMode (mode: INTEGER); 

Sets the transfer mode through which the 
ifttMap. The mode may be any one of the pa 




Is transferred 
• lining modes: 



onto the 



patCopy 
patOr 



patXor 
patBic 



notPatCopy 
notPatOr _ 



If the mode Is one of 
drawing is performed. 






1 

>n^posit 




notPatXor 
jiptPatBic 



the -^st neifc • liaia tg 'modes ((or non^positive) , no 
The current pen mode catu.be obtained** as an 
integer in the variable thePorf.pnMode. The Initial pen mode is 
patCopy, in which the pen pattern is copied directly to the f€ne\ bitMap 



PROCEDURE PenPat (pat: Pattern); 

/ 
Sets the Tepea*4«g5 pattern that is used by the pen in this grafPort. 

Standard patterns are defined for White, Black, Gray, LtGray, and 

DkGray; the initial pnPat is Black. The current pen pattern can be 

obtained in the variable thePorf.pnPat, and this value can be assigned 

(but not compared!) to any other variable of type Pattern. 



PROCEDURE PenNormal; 






Resets the iiitial state of the pen in Jsfeie grafPort^: 



(LA- 



0jm^ 



PnSize 
PnMode 



(1,1) 
patCopy 
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TO* 



PnPat Black 

The pen location is not changed. V \. 

PROCEDURE MoveTo (h,v: INTEGER); 

Moves the pen to location (h,v) in the local coordinates of the current 
grafPort. No drawing is performed. , . 



PROCEDURE Move (dh.dv: INTEGER); 

Moves the pen a distance dh horizontally and a distance dv vertically X 
from its previous location. The positive directions are down and \ 
right. No drawing is performed. \ / 



M' 



\?^PROCEDURE LineTo (h,v: INTEGER); 

<3 Draws a line from the^current) pen location to the location specified 
§*»(in local coordinates) 7>yh and v. The new pen location becomes (h,v) 
y after the line is drawn . See the general discussion on drawing. j 




ind 



Draws a 
from its<p 
right. ^Th 




If a ^region is open 

jT"to the region's boundary. a 1^ 

Iv: INTEGER); . JV^ v^ ^ AV / 

ince dh horizontally and a distance dv vertically - 



1R JLUi-UICU^ L11C Ll.ajCV.l.UlJ' \JM- |1_11C LIC« J.XUC 

mathematlcaXiy - ad~3e$T to the region's boundary. a ^U _>4m 

PROCEDURE Line (/h,dv: INTEGER);^ , ^V^ 



tance dh horizontally 
^ocation^/The : posit ive_jiire ct ions are down and _ 
ocation ^^assume^y the coordinates of\ the end of the 



F 



? 

y„* 



line. See the general discussion on drawing. 



If a region is open and being formed, the trajectory of the new line Is U 
mathematically added to the region's boundary. \ 



Character-Drawing Procedures 



Each grafPort has its own character style, and all these procedures 
^deal with)the character style of the current port. 



y U >< 



PROCEDURE DrawChar (ch: CHAR); 








\iTk^&&$3 



Places the selected character to the right of the pen location, and 
advances the pen the width of the character. If the character is not 
in the font, the font's "missing symbol" will be drawn; if the font's 
"missing symbol" is itself missing, expect a crash (In this incarnation 
of QuickDraw). 
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PROCEDURE DrawString (s: Str255); 

Performs consecutive calls to DrawChar for each character in the 
supplied string; the string is placed beginning at the current pen 
location jrfd extending right. No formatting (carriage returns, line 
feeds, /tty is performed by QuickDraw. The pen location ends up to the 
right ck_^rhe last character in the string. 

( eye) 

If the string of characters extends beyond the clipping 

boundaries of the current grafPort, clipping will be 

performed as norma^W'Dut the pen location will remain to 

the right of the last character completely or partially , I A,^-^ 

drawn, not the last character in the string. This is the , /,,,'/ 



only exception to the rule that clipping never affects A (.f T ' ^ 

PROCEDURE DrawText (textBuf: WordPtr; f irstByte.byteCount : INTEGER); 

jDraws text from an arbitrary structure in memory specified by textBuf , 
s tar tingV firs tByte bytes into the structure and continuing for 
byteCount bytes, and draws them on the screen in a string. The string 
is placed beginning at the current pen location and extending right. 
No formatting (carriage returns, line feeds ^fcj is performed by 
QuickDraw. The pen location ends up to the rtgnt of the last character 
in the string (but see the warning for DrawString, above). 

The textBuf parameter, although of type WordPti^is really a byte^^^ 
pointer; it may be an odd value to point atT^eithe^Nbyte in a wordy / ""} 

V ^ = P = ^1 "" -J < 

FUNCTION CharWidth (ch: CHAR): INTEGER; ? 



Returns the width of the given character; this fram e value is added to 
the pen horizontal coordinate whenever the specified character is 
drawn. The CharWidth includes the effects of the extra space 
parameter. 

FUNCTION StringWidth (s: Str255): INTEGER; 

Returns the width of the given text string; this same value is added to 
the pen horizontal coordinate whenever the specified string is drawn. 
The StringWidth includes the effects of the extra space parameter; if 
you change this parameter before actually drawing the string, your 
width will not be accurate. 

( eye) 

StringWidth and TextWidth always return the true length 
of the string as it would be drawn, regardless of 
clipping. But the actual difference between the 
beginning and ending pen locations may be affected by 
clipping (see DrawString and DrawText, above): In such 
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cases, the distance the pen moves while drawing the 
string is noL the same as the width as ^iven by 
StringWidth or TextWidth. 



FUNCTION TextWidth (textBuf: WordPtr; f IrstByte.byteCount : INTEGER): 
INTEGER; A .„ S ' , 



Returns the width of the ^Id'uu text fSSBfWR arbitrary structure in 
memory specified by textBuf, starting firstByte bytes into the 
structure and continuing for byteCount bytes. The TextWidth includes 
the effects of the extra space parameter; if you change this parameter 
before actually drawing the text, your width will not be accurate. 
(See also the warning for StringWidth, above). 

The textBuf parameter, although of type WordPtr, is really a byte 
pointer; It may be an odd value to point at either byte in a word. 

PROCEDURE SetChar (chS: CharStyle) ; i, 

Sets the( preparedV chS to be the character style of the cur rent 
grafPort. You must initialize all fields of a CharStyle hfore 
installing It with SetChar. Calling SetChar(charNormal) will restore 
the default character font. 

I 
After calling SetChar, all previously calcuated character, string, and 

text widths may become invalid due to a new font or extra space 

parameter. 

The current character style may be retrieved from the variable 
thePort" .chStyle. 



Calculations with Rectangles _^ 

( hand) 

Calculation procedures are independent of the current 
coordinate systems; a calculation will operate the same 
regardless of which grafPort is yficfTve). 

PROCEDURE SetRect (VAR r: Rect; left, top, right, bottom: INTEGER); 

Utility to assign four boundary coordinates to a rectangle. The result 
is a rectangle with coordinates (left, top, right, bottom) . . A.W& 

This/procedure is supplied to help you shorten your source - eoda ; if you 
wantj^more readable neode at the expense of length, you can assign 
Integers (or points) directly into the rectangle's fields. Therezis no 
significant code size or execution speed advantage to either method; 
one's just easier to write, and the other's easier to read. 
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PROCEDURE OffsetRect (VAR r: Rect; dh.dv: INTEGER); 

"Moves" the coordinates of a rectangle a distance dh horizontally and a 
distance dv vertically; positive directions are right and down. The 
rectangle retains its shape and size; only its coordinate location^** 
altered. ~~ \ 

PROCEDURE InsetRect (VAR r: Rect; dh.dv: INTEGER); 

Shrinks or g ftt k c a rectangle. The top and bottom are moved towards the 
center by the amount specified in dv; the left and right sides are 
moved in by the amount in dh. The effect is to alter the size by 2*dh 
horizontally and 2*dv vertically, with the rectangle remaining centered 
in the same place on the coordinate plane. If dh or dv is negative, 
the appropriate pair of sides is moved outwards instead of Inwards. 

If either the resultant width or height becomes less than 1, the 
rectangle is set to the null rectangle (0,0,0,0). 



FUNCTION SectRect (srcRectA.srcRectB: Rect; VAR dstRect: Rect): 
BOOLEAN; 

Calculates the rectangle that is the intersection of the two input 
rectangles, and returns TRUE if they indeed intersect and FALSE if they 
do not. Rectangles that "touch" at a line or a point are not 
considered intersecting, because their Intersection rectangle (really, 
in this case, an intersection line or point) does not enclose any bits 
on the^tMap. 

If the rectangles do not intersect, the destination rectangle is 
(0,0,0,0). SectRect works correctly even if on^ of the source 
rectangles is uc ad ao .the destination 



( hand) 





If the rec 



graf Ports, j their mathematical int. 

it tb^t 



different 
eysection ( 

their physical 



SectRect) may be different 

intersection on the screen. To adjust the points of a 
rectangle into another port's coordinate system, see the 
Local ToGlobal and GlobalTo Local calls. 








v»V 



FUNCTION PtlnRect (pt: Point; r: Rect): BOOLEAN; ctr^Xh^^' 
Determines if the pixel below and to the right of the eiven kpoint is J 



enclosed in the given rectangle, and returns TRUE if so aatf FALSE 
not. (The chosen pixel is the one that would be altered by a Lin 

a 



if 






. _ __ a Linej.0,0) 

at the" current pen location with a pen size of (l,l)^Both the 
and the rectangle must be in the same coordinate systemiv 

7 , lM W} U 



/ 







> 



u 



2/17/82 Espinosa 



/QUICK. DRAW/QUIKDRAW . 5 



QuickDraw Programmer's Guide • 15 February 1982 



Page 0040 of 0064 



Apple Macintosh Early Technical Information • Inside Macintosh 



40 QuickDraw Programmer's Guide 



Graphical) Operations on Rectangles 



PROCEDURE PaintRect (r: Rect); 

Paints the specified rectangle with the pen pattern and mode,. The 
rectangle on the bitMap is filled with the pnPat^according to the 
transfer mode specified by pnMode. The pen 4£ei^S3£> at .its ori 
location. 





PROCEDURE FrameRect (r: Rect); 

Draws a hollow outline with the pen pattern, mode, and size just inside 
the specified rectangle. The outline is as wide as the pen width and 
as tall as the pen h eight . The outline on the bitMap is filled with 
the pnPat, according to the transfer mode specified by pnMode. The pen 
re mains at its original location. 

If a region is open and being formed, the outside outline of the new 
rectangle is mathematically added to the region's boundary. 



fa>\ 



PROCEDURE EraseRaet (r*: Rect); 



The 



Paints the specified rectangle with the background pattern bkPat. j.hc 
pnPat and pnMode are ignorecRythe pen remains at its original location 



PROCEDURE InvertRect (r: Rect); 

The bits enclosed by the specified rectangle are inverted: every white 
bit becomes black and every black bit becomes white. The pnPat, 
pnMode, and bkPat are all ignored^/^he pen remains at its original 
location. • 



PROCEDURE FillRect (r: Rect;_pat: Pattern); 

Paints the specified rectangle with bfie given pattern. The pnPat, 
pnMode, and bkPat are all ignored^ Ahe pen remains at its original 
location. ( 



PROCEDURE ScrollRect (dstRect: Rect; dh.dv: INTEGER; \updateRgn: 
rgnHandle); 

ScrollRect alters only those bits inside the dstRect, the visRgn, the 
clipRgn, the portRect, and the portBits. bounds. The bits in the z 
intersection of all those get shifted a distance of dh horizontally and 
a distance of dv vertically; positive directions are right and down. 
Bits that are shifted out of the scroll area are lost; they are neither 
placed outside the area nor saved/off) The background pattern bkPat is 
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scrolled into) the space created by the scrol 
s ch"ange~d~7to contain all bits that were 



Before Scvo'lRca Afwr $cmmct(dstRecz,-w,5...) 
5t 




In addition, updateRgn 



> 



-jfU ^ 



:.U- 







rtof^b 



Figure 16. Scrolling 
ixolling, 2 







PROCEDURE XferRe^r. (srcBits.dstBits: .^itMap; srcRect.dstRect: Rect; 




«Mrbit imagejbetween any two bitMaps, or -from a 



Transfers _^_„. _ _ 

ppt-hom 4nhn an v recta ngular areaT within a^jfttMap. The transfer flay be 
'performed in an^_^f_jlEiI&6A rans f er modes. The transfer is always 
clipped to the^boundary K*)of the destination bitMap, and, if the 
destination bitMap is the current g'raf Port's portBitSi, the transfer is 
clipped inside the clipRgn, visRgn, \and portRect, too) 



\yy 



1 







MJrk^A 



L 



ftf 



iXJisu*^. 



^ -fldUUs 




9) 



2/17/82 Espinosa 



/QUICK. DRAW/QUIKDRAW . 5 



QuickDraw Programmer's Guide • 15 February 1982 



Page 0042 of 0064 



Apple Macintosh Early Technical Information • Inside Macintosh 



42 QuickDraw Programmer's Guide 




v* 



IsA 



j*»\ 



7 



Pattern 



Destiimrum BitMo-p 






£cs 



Figure 17. Operation of XferRect 



The JJstRect coordinates are in terms of the dstBits. bounds coordinate 
system; the SrcRect coordinat es are i nterns of„l he srcB itg -hounds ^**^ 
coordinates. When ri iop y iftg ~~Tr"~om the source to the destination, the top 
left corner of the source rectangle is aligned with the top left corner 
of the destination rectangle; the size of the source rectangle is 
ignored. 



QuUUu 



a>{- 



In the source'a mLLag transfer modes, each bit of the source, is 
transferred to the destination according to the rules of that mode, 
the pattern is ignored (we suggest you set it to white). The eight 
source-^M^aag modes are as follows: 

srcCopy srcXor notSrcCopy notSrcXor 

srcOr srcBic notSrcOr notSrcBic 



and 



In the pattern-««*ilg- transfer modes, the specified pattern is 
/trans£e"?ejl into the destination rectangle according to the chosen mode. 

The source bitMap and source rectangle are not used; we suggest you set .j^-.^ 
these to the destination bitMap and destination rectangle. ~|w. *^U? ^AMJ^^ 



' ' patCopy patXor 



patOr 



patBic 



notPatCopy 
notPatOr 



notPatXor - 
notPatBic 



_ Theserfr'ansfer modes are useful for filling a rectangle that is outside 
0~~*f the current grafPort. For filling a rectangle inside the current 
grafPort, however, the FillRect procedure is much easier to use. 

Of . h e- ^ /wJits &-£*■*/ Aw<uX^ 

Graphical) Operations on Ovals U \J_ . (f 
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PROCEDURE PaintOval (r: Rect); 

Paints an oval just inside the specified rectangle with the pen pattern 
and mode. The oval on the bitMap is filled with the pnPat, according 
to the transfer node specified by pnHode. The pen remains at its 
original location. 



PROCEDURE FrameOval (r: Rect); 

Draws a hollow outline with the pen pattern, mode, and size just inside 
the oval that fits inside the specified rectangle. The outline is as 
wide as the pen width and as tall as the pen heieht. The outline on 
the bitMap is filled with the pnPat, according to the transfer mode 
specified by pnMode. The pen remains at its original location. 

If a region_is open and being formed, the outside outline of the new 
oval is (ma tThematJcaJLly? added to the region's boundary. 



PROCEDURE EraseOval (r: Rect); 

Paints an oval just Inside the specified rectangle with the background 
pattern bkPat. The pnPat and pnMode are ignored; the pen remains at 
its original location. 



PROCEDURE InvertOval (r: Rect); 

The bits enclosed by an oval just inside the specified rectangle are 

inverted: every white bit becomes black and every black bit becomes 

white. The pnPat, pnMode, and bkPat are all ignored; the pen remains 
at its original location. 



PROCEDURE FillOval (r: Rect; pat: Pattern); 

Paints an oval just inside the specified rectangle with the given 
pattern. The pnPat, pnMode, and bkPat are all Ignored; the pen remains 
at its original location. 




Graphic(a]j Operations on Rounded-Corner Rectangles 



PROCEDURE PaintRoundRect (r: Rect; ovalWidth.ovalHeight: INTEGER); 

Paints the specified rounded-corner rectangle with the pen pattern and 
mode. The rounded-corner rectangle on the bitMap is filled with the 
pnPat, according to the transfer mode specified by pnMode. The pen 
remains at its original location. OvalWidth and ovalHeight specify the 
diameters of curvature for the corners. 
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Figure 18. Rounded-Corner Rectangles 



PROCEDURE FrameRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 

Draws a hollow outline with the pen pattern, mode, and size just inside 
the specified rounded-corner rectangle. The outline is as wide as the 
4>en width and as t all a s the pen height. The outline on the bitMap is 
filled with the pnPat, according to the transfer mode specified by 
pnMode. The pen remains at its original location. OvalWidth and 
ovalHeight specify the diameters of curvature for the corners. 

If a region is open and being formed, the outside outline of the new 
rounded -corner rectangle is mathematically added to the region's 
boundary. 



PROCEDURE EraseRoundRect (r: Rect; ovalWidth, ovalHeight: INTEGER); 

Paints the specified rounded-corner rectangle with the background 
pattern bkPat. The pnPat and pnMode are ignored; the pen remains at 
its original location. OvalWidth and ovalHeight specify the diameters 
of curvature for the corners. 



PROCEDURE InvertRoundRect (r: Rect; ovalWidth, ovalHeight: INTEGER); 

The bits enclosed by the specified rounded-corner rectangle are 
inverted: every white bit becomes black and every black bit becomes 
white. The pnPat, pnMode, and bkPat are all ignored; the pen remains 
at its original location. OvalWidth and ovalHeight specify the 
diameters of curvature for the corners. 
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PROCEDURE FillRoundRect (r: Rect; ovalWidth.ovalHeight : INTEGER; pat: 
Pattern); 

Paints the specified rounded-corner rectangle with the given pattern. 
The pnPat, pnMode, and bkPat are all ignored; the pen remains at its 
original location. OvalWidth and ovalHeight specify the diameters of 
curvature for the corners. 



Calculations with Regions 



FUNCTION NewRgn: RgnHandle; 



^ 



Creates space for a new* dynamic , variable-size region, initializes it 
to the empty region, and returns a handle to the new region. Only this 
tocedw*" creates new regions; all other procedures just alter the size 
and shape of regions you create. 

Never refer to a region without using its handle; regions are too big 
and awkward to be carried around any other way. 

( eye) 

You must call NewRgn to initialize a region's handle 
before that handle can be used in any region drawi 
/circulation procedure. 

PROCEDURE DisposeRgn (rgn: RgnHandle); 

"Deallocates space for the region whose handle is supplied, and returns 
the memory used by the region to the free memory pool. Use this 
after you are completely through with a temporary region. 



( eye) 

NEVER use a region once you have deallocated itj 

will risjt being_Jhung bv_ dangling pointers! ^ Beware of 

SetClipRgn and StTtVTiRgnT'they don't duplicate the 

region, they only make a c opy of the han dle. If 
deallocate a region that /y"ou previouslv7 s^tr~to"~~b~e" your 
clipRgn, your clipping goes away and very strange things 
will occur 





k^$>> 




PROCEDURE CopyRgn (srcRgn, dstRgn: RgnHandle); 




Copies the, mathematical structure of srcRgn into dstRgn; i.e. it makes 
a duplicate copy of srcRgn. Once this is done, srcRgn may be altered 
(even disposed of) without affecting dstRgn. 
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PkOCEDURE SetKectRgn (rgn: RgnHandle; left , top.right .bottom: INTEGER); 

Destroys the previous C 4 ata structur e^ of rgn, then sets the new 
structure to the rectangle specified by left, top, right, and bottom. 
This is a good way to obtain a rectangular region, and also to set a 
region to the null region (0,0,0,0). 

If the rectangle specified is not rectangular (i.e. left>=right or 
top>=bottom) , the region is set to the null region. 



PROCEDURE RectRgn (rgn: RgnHandle; r: Rect); 

Destroys the previous data structure of rgn, then sets the new 
structure to the rectangle spe cifie d by r. This is operationally 
synonymous with SetRectRgn^e"xcept~~the input rectangle is defined by a 
rectangle, not four bo 



PROCEDURE OpenRgn; 




if 



OpenRgntells^uickDraw to allocate/ temporary space and start saving 
line segments) and framed shapes fee* later be- processed as a region 
definition. The global BOOLEAN variable RgnSave Indicates whether a 
region is open; flipping RgnSave FALSE disables the collection of lines 
and frames, and restoring RgnSave TRUE resumes the region definition. 

All Line, LineTo, vFrameRect, FrameOval, FrameR mmdBpt-t-, anil FratnpRy 
procedure calls while" a region" is open affect the outline of the 
region. Only the line endpoints and shape boundaries affect the region 
definition, not the pen mode, pattern, size, or location. In fact., — 
it's best to set the penSize to (0,0) before drawing a region: «*the 
pen hangs below and to the right on a line, drawing lines with even the 
smallest pen will change bits that do not mathematically belong to the 
region. 

The outline of a region is mathematically defined and infinitely thin, 
and separates the bitMap into two groups of bits: those within the 
region and those outside it. A region should consist of one or more 
^closed loqps>. Each frame itself constitutes a loop; any lines drawn 
with Line or LineTo should connect with each other or with a frame. 
Even though the on-screen presentation of a region is clipped to the 
portRect, etc., the creation of a region is not; you can define a 
region anywhere on the coordinate plane with complete disregard for the 
location of various grafPort entities on that plane. 



.V 



|-},V 



y 



( eye) 



Do not perform an OpenRgn while another region Is already 
open. All open regions but the most recent will behave 
strangely. 
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PROCEDURE CloseRgn (dstRgn: RgnHandle); 

Stops the collection of endpoints and outlines, organizes them into a 
region definition, and saves the resulting region into the region 
indicated by dstRgn. You should perform one and only one CloseRgn for 
every OpenRgn. 



Here's an example of how to create 
shape, close the region, and draw 

Barbell := NewRgn; 

PenSize(0,0); 

OpenRgn; 

SetRect( tempRect, 20, 20, 
^rameOvalCtempRect) ; 

SetRect( tempRect , 30, 30, 
"^rameRect( tempRect) ; 
SetRect( tempRect, 80, 20, 
^-FrameOval(tempRect); 
CloseRgn(Barbell) ; 
FillRgn(Barbell, Black) ; — 
DisposeRgn( Barbell) 



and open a region, define a barbell 

it! •/:' 

^^^\fmake a new region} * 

[pdon't draw it on the screen} 
{begin collecting stuff} 
30,50) 



80,40) 
90,50) 




f6raw"the left weight} 
ftraw // the bar} 
{<iraw // the right weight} 



y) \ {we're done; save in barbell} 
rtodraw it! } ** 

{we don't need you anymore...} 



PROCEDURE OffsetRgn (rgn: RgnHandle; dh.dv: INTEGER); 

Mathematically moves the region a distance of dh horizontally and dv 
vertically; positive directions are right and down. The region retains 
its size and shape; it merely is moved on the coordinate plane. 



PROCEDURE InsetRgn (rgn: RgnHandle; dh.dv: INTEGER); 

Shrinks or ^rowpthe region. All points on the r,egion boundary are 
moved inwards a distance of dv vertically and dh horizontally; if -dh or 
dv is negative, the points are moved outwards in that direction. 
InsetRgn leaves the region "centered" at the same position, but moves 
the outline in (for positive values) or out (for negative values). 
InsetRgn of a rectangular region works just like InsetRect (see). 



PROCEDURE SectRgn (srcRgnA,srcRgnB, dstRgn: RgnHandle); 

Calculates the intersection of two regions and places the intersection 
in a third region. THIS DOES NOT CREATE THE DESTINATION REGION: you 
must use NewRgn to create the dstRgn before you call SectRgn. The 
destRgn can be one of the source regions, if desired. 

If the regions do not intersect, or one of the regions is the empty 
region, the destination is set to the empty region, which you can test 
with the EmptyRgn function. 
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If the regions were defined in different grafPorts, the mathematical 
intersection (froci SectRgr.) v..ay not correspond to their physical 
intersection on the screen. To adjust a region into another port's 
coordinate system, see the LocalToGlobal and GlobalToLocal calls. 

PROCEDURE UnionRgn (srcRgnA.srcRgnB, dstRgn: RgnHandle); 

Calculates the union of two regions and places the union in a third, 
region. THIS DOES NOT CREATE THE DESTINATION REGION: you must use 
NewRgn to create the dstRgn bs^re you call UnionRgn. The destRgn can 
be one of the source regions, if desired. 

If both regions are empty, the destination is set to the empty region, 
which you can test with the EmptyRgn function. 

If the regions were defined in different grafPorts, the mathematical 
union (from UnionRgn) may not correspond to their physical union on the 
screen. To adjust a region into another port's coordinate system, see 
the LocalToGlobal and GlobalToLocal calls. 

PROCEDURE DiffRgn (srcRgnA.srcRgnB, dstRgn: RgnHandle); 

Subtracts srcRgnB from srcRgnA and places the difference in a third 
region. THIS DOES NOT CREATE THE DESTINATION REGION: you must use 
NewRgn to create the dstRgn befe^re you call DiffRgn. The destRgn can 
be one of the source regions, Wt desired. 

If the first source region is the empty region, the destination is set 
to the empty region, which you can test with the EmptyRgn function. 

If the regions were defined in different grafPorts, the mathematical 
difference (from DiffRgn) may not correspond to their physical 
difference on the screen. To adjust a region into another port's 
coordinate system, see the LocalToGlobal and GlobalToLocal calls. 

PROCEDURE XorRgn (srcRgnA,srcRgnB, dstRgn: RgnHandle); 

Calculates the difference between the union and the intersection of two 
regions and places the result in a third region. THIS DOES NOT CREATE 
THE DESTINATION REGION: you must use NewRgn to create the dstRgn 
begore you call XorRgn. The destRgn can be one of the source regions, 
if desired. 

If the regions are coincident, the destination is set to the empty 
region, which you can test with the EmptyRgn function. 

If the regions were defined in different grafPorts, the mathematical 
Xor (from XorRgn) may not correspond to their physical Xor on the 
screen. To adjust a region into another port's coordinate system, see 
the LocalToGlobal and GlobalToLocal calls. 
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DtisriruitiDn. BitMap 



Figure 19. Operation of XferRgn 

The DstRect and MaskRgn coordinates are in terms of the dstBits. bounds 
coordinate system; the SrcRect coordinates are in terms of the 
srcBits. bounds coordinates. When copying from the source to the 
destination, the top left corner of the source rectangle is aligned 
with the top left corner of the destination rectangle; the size of the 
source rectangle is ignored. 



In the source-uiinf, transfer modes, each bit of the source is 
transferred to the destination according to the rules of the mode, 
pat parameter is ignored; we recommend you set it to white. The 
source MtfAwg 1 m odes are as follows : 



srcCopy 
srcOr 



srcXor 
srcBic 



notSrcCopy 
notSrcOr 



notSrcXor 
notSrcBic 



The 



In the pattern-aisiSg transfer modes, the specified pattern is 
transfered Into the destination rectangle according to the chosen mode. 
The source bitMap and rectangle are not used; we suggest you set these 
to the destination bitMap and rectangle. 



patCopy 
patOr 



patXor 
patBic 



notPatCopy 
notPatOr 



notPatXor 
notPatBic 



The*ef transfer modes are useful for filling a region that is in some 
other Graf Port. 



Miscellaneous Utilities 



2/17/81 Espinosa 



/QUICK. DRAW/QUIKDRAW . 6 



QuickDraw Programmer's Guide • 15 February 1982 



Page 0052 of 0064 



Apple Macintosh Early Technical Information • Inside Macintosh 



vV 



52 QuickDraw Programmer's Guide 






FUNCTION Random: INTEGER; / " £>' 

Returns a 16-bit signed integer, uniformly distributed pseudo-random. 



* 



FUNCTION GetPixel (h,v: INTEGER): BOOLEAN; I \fJ? ^ 









Peeks^at a single bit in memory (perhaps a pixel) and returns TRUE if 

the(3ot)is black and FALSE if the dot is white. The selected pixel -is 

the one immediately below and to the right of the point whose 

coordinates are given in h and v; these points are in the local \J 

coordinates of the current grafPort. There is no guarantee that the 

pixel actually belongs to the port, however^ it cay have been drawn by 

a port overlapping the current one. To see if the point indeed belongs 

to the current. port, perform a PtInRgn(pt ,thePort~ .visRgn) . 

PROCEDURE AddPt (src: Point; VAR dst: Point); 

Adds the first point to the second, returns the sum in the second 
point. 

PROCEDURE SubPt (src: Point; VAR dst: Point); 

Subtracts the first point from the second, returns the result in the 
second point. 

PROCEDURE SetPt (VAR pt: Point; h,v: INTEGER); 

Assigns two integer coordinates to a variable of type point. 

PROCEDURE LocalToGlobal (VAR pt: Point); 

Converts the given point from the current grafPort's local coordinate 
system into a global coordinate system with the origin (0,0) at the top 
left corner of the port's bitMap (such as the screen). This global 
point can then be compared to other global points, or be changed into 
the local coordinates of another grafPort. For example, if the 
rectangle ballRect is defined in the gamePort grafPort, and you want to 
use that rectangle in the selectPort grafPort, you would calculate the 
ball's coordinates like this: 

SetPort( gamePort); { start in origin port} 

SelectBall := ballRect; {make a copy to be moved} 

LocalToGlobal(SelectBall.topLeft); { put both corners into } 
LocalToGlobal(SelectBall.botRight); { global coordinates } 

SetPort(selectPort); { switch to destination port } 

GlobalToLocal(SelectBall.topLeft); { put both corners into } 

GlobalToLocal(Selectball.botRight); { these local coordinates } 

Fill0val(SelectBall,BallColor,8,8); { Now you have the ball! } 
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You can also convert rectangles and regions into global coordinates 
without performing a LocalToGlobal call for each point. Simply perform 
LocalToGlobal for one point (for example, the top left corner of the 
region's bounding box), then use OffsetRect or OffsetRgn to move the 
rest of the object the distance of displacement: 

CopyRgn(myRgn, tempRgn); 

tempPoint := tempRgn" .rgnBBox. topLef t; 

LocalToGlobal ( tempPoint) ; 

Of fsetRgn(tempRgn, tempPoint. h, tempPoint. v) 



PROCEDURE GlobalToLocal 

Takes a point expressed in global coordinates (with the top left corner 
of the bitMap as coordinate (0,0)) and converts it into the local 
coordinates .of the current grafPort. The global point can be obtained 
with the LocalToGlobal call (see above). 

You can convert global-coordinate rectangles and regions into local 
coordinates without performing a GlobalToLocal call for each point. 
Simply perform GlobalToLocal for one point (for example, the top left 
corner of the region's bounding box) , then use OffsetRect or OffsetRgn 
to move the rest of the object the distance of displacement: 

SetPort(MyNewPort) ; 

tempPoint := globRgn .rgnBBox.topLef t; 

GlobalToLocal(tempPoint); 

Of fsetRgn(globRgn, -tempPoint. h, -tempPoint. v) 



PROCEDURE Stuff Hex (thingptr: WordPtr; s:Str255); 

Pokes bits (expressed as a string of hexadecimal digits) into anyidata 
structure. This is a good way to create cursors, patterns, or bit 
images to be "stamped" onto the screen with XferRect. For example, 

StuffHex((3stripes, '0102040810204080') 



places a striped pattern into the pattern variable stripes. Beware; 
there is no range checking on the size ofthe destination variable; 
it's easy to overrun the variable and^tfasK) something if you don't know 
what you're doing. ^ ^ 



P 



USING QUICKDRAW FROM ASSEMBLY LANGUAGE 



All Macintosh User Interface ToolBox routines can be called from 
assembly-language programs as well as from Pascal. When you write an 
assembly-language program to use these routines, though, you must 
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emulate Pascal's parameter passing and variable transfer protocols. 

The remainder of this section discusses how to use the QuickDraw 
constants, global variables, data types, procedures and functions from 
assembly language. 

The primary aid to assembly-language programmers is a file named 
GRAFEQU.TEXT. If you .INCLUDE this file when you assemble your 
program, all the QuickDraw constants, offsets to locations of global 
variables, and offsets into the fields of structured types will be 
available in symbolic form to your programs. 



Constants ; 

QuickDraw constants are stored in the GRAFEQU.TEXT file, and you can 
use the constant values symbolically. For example, if you've loaded 
the effective address of the thePort~.chStyle.mode field into address 
register A2, you can set that field to the srcXor mode with this-. 
statement: 

MOVE.W #SRCX0R,(A2) 

The only constants defined at this point are the sixteen transfer 
modes. 



Data Types . 

Pascal's strong typing ability lets you write Pascal programs without 
really considering the size of a variable. But in assembly language, 
you must keep track of the size of every variable. The sizes of the 
standard Pascal data types are as follows: 

Type Size 

INTEGER 

LONGINT 

Pointer 

BOOLEAN 

REAL 

CHAR 

INTEGERS and LONGINTs are in two's complement form; BOOLEANS have their 
boolean value in bit 8 of the word (the low-order bit of the byte at 
the same location); CHARs are stored in the high-order byte of the 
word; and REALs are in the KCS standard format. 

QuickDraw simple data types are constructed out of these fundamental 
types. 

Type Size 



Word 


(2 bytes) 


Long 


(4 bytes) 


Long 


(4 bytes) 


Word 


(2 bytes) 


Long 


(4 bytes) 


Word 


(2 bytes) 



WordPtr 


Long 


(4 bytes) 


Str255 


Page 


(256 bytes) 


Pattern 




8 bytes 


Bitsl6 




32 bytes 
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Other data types are constructed as records of variables of the above 
types. The size of such a type is the sum of the sizes of all the 
fields in the record; the fields appear in the variable with the first 
field in the lowest address. For example, the data type BitMap, which 
is defined like this: 

BitMap = RECORD 

baseAddr: WordPtr; 
rowBytes: INTEGER; 
bounds: Rect 

END» 

; 

would be arranged in memory as seven words: a long for the baseAddr, a 
word for the rowBytes, and four words for the top, left, right, and 
bottom parts of the bounds rectangle. To assist you in referring to 
the fields inside a variable that has a structure like this, the 
GRAFEQU.TEXT file defines constants that you can use as offsets into 
the fields of a structured variable. For example, to move a bitMap's 
rowBytes value into D3, you would execute the following instruction: 

MOVE . W MYBITMAP+ROWBYTES , D3 

$ Displacements are given in the GRAFEQU.TEXT file for all fields of all 
« data types defined by QuickDraw. 



„ . . . , . .. . . , n^^f or 



vO To do double indirectiong^for example, to get at the top coordinate of 
~a region' sThtrondtag. bow, you perform an LEA indirectly to obtain the 
effective address from the handle: 

MOVE.L MYHANDLE.A1 ; Load handle into Al 

MOVE.L (A1),A1 ; Use handle to get pointer 

MOVE.W RGNSIZE+T0P(A1),D3 ; Load value using pointer 



( eye) 



For regions (and all other variable-length structures 
with handles) , you must not move the pointer Into a 
register once and just continue to use that pointer; you 
must do the double indirection each time. Every 
QuickDraw, ToolBox, or memory management call you make 
can possibly trigger a heap compaction that renders all 
pointers to movable heap items (like regions) invalid. 
The handles will remain valid, but pointers you've 
obtained through handles can be rendered invalid at any 
subroutine call or trap in your program. 



Global Variables 

Global variables are stored in a special section of Macintosh low 
memory; register A5 always points to this section of memory. The. 
GRAFEQU.TEXT file defines a constant GRAFGLOB that points to the 
beginning of the QuickDraw variables in this space, and other constants 
to point at the individual variables. To access one of the variables, 
just sum the constants and index off of A5. For example, if y6vTve\ are 
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preparing a bitMap record and you want that bitMap to share the same 
bit image as the screenBits global variable, you'd perform the 
following instruction: 

MOVE. L GRAFGL0B+SCREENBITS+BASEADDR(A5) .MYBITMAP+BASEADDR 



Procedures and Functions 

To call a QuickDraw procedure or function, you must push all parameters 
to that function on the stack, then JSR to the function or procedure. 
When you link your program with QuickDraw, these JSRs are andiAted to 
refer to the jump table in low RAM, so that a JSR into the table 
redirects you to the actual location of the procedure or function. 
After the procedure or function has unstacked all its parameters and 
performed its operation, it returns to you with the stack cleared. 

The only difficult part about. calling. QuickDraw procedures and 
functions is stacking the parameters. You must follow some strict 
rules: 

- Save all registers you wish to preserve before you begin pushing 
parameters. Any QuickDraw procedure can destroy the contents of 
the registers A0, Al, D0, Dl, and D2, but the others are never 
altered. 

- Push the parameters in the order that they appear in the Pascal 
procedural interface. 

- For integers, booleans, and characters, push a word; for pointers, 
handles, long integers, and reals, push a long. 

- For any structured variable longer than four (4) bytes, push a 
pointer to the variable. 

- For all VAR parameters, regardless of size, push a pointer ti> the 
variable. 

- When calling a function, FIRST push a null entry equal to the size 
of the function result, THEN push all other parameters. The 
result will be left on the stack after the function returns to 
you. 

This makes for a lengthy interface, but it also guarantees that you can 
mock up a Pascal version of your program, and when you later translate 
it into assembly code, it works the same. For example, the Pascal 
statement 

Blackness :» GetPixel(50,MousePos.v) ; 

would be written in assembly language like this: — 

CLR.W *(SP) ; Save space for boolean result 

MOVE.W #32, -(SP) ; Push constant 50 (decimal) 
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MOVE.W MOUSEPOS+V,-(SP) 
JSR GETPIXEL 
MOVE.W (SP)+, BLACKNESS 



Push the value of MOUSEPOS.V 

Call routine 

Fetch result from stack. 



This Is a simple example, pushing and pulling word'long constants. 
Normally, you'll be pushing more pointers, using the PEA (Push 
Effective Address) instruction: 

FillRoundRect(MyRect,l,thePort~.penSize.v, White) ; 

PEA MYRECT ; Push pointer to MYRECT 

MOVE.W #1,-(SP) ; Push constant 1 

MOVE.W GRAFGLOB+THEPORT+PENSIZE+V(A5) ,-(SP) 

; Push value of ThePort~ .penSize.v 
PEA GRAFGL0B+WHITE(A5) ; Push pointer to global var White 
JSR FILLROUNDRECT ; Call the subroutine 

Beware that the horizontal and vertical parts of a point do not appear 
in the same order in the data structure as they do in a procedure call I 
Even though you can move a point around with a MOVE.L instruction, you 
can't push that point as a parameter to a procedure which requires two 
integer coordinates. For example, to call MoveTo with a point 
argument, you must do two separate pushes: 



MOVE.W MOUSEPOS+H,-(SP) 
MOVE.W MOUSEPOS+V,-(SP) 
JSR MOVETO 



Push horizontal position 
Push vertical position 



Just doing a MOVE.L MOUSEPOS.-(SP) would transpose the vertical and 
horizontal results, and make MoveTo work funny. 



SUMMARY OF QUICKDRAW 



CONST srcCopy 


= 


0; 


{ Destination 


srcOr 


= 


1 


{ Destination 


srcXor 


= 


2 


{ Destination 


srcBic 


= 


3 


{ Destination 


notSrcCopy 


= 


4 


{ Destination 


notSrcOr 


= 


5 


{ Destination 


notSrcXor 


- 


6 


{ Destination 


notSrcBic 


a 


7 


{ Destination 


patCopy 


= 


8 


, { Destination 


patOr 


= 


9 


, { Destination 


patXor 


- 


If 


t; { Destination 


patBic 


- 


1 


.; { Destination 


notPatCopy 


ss 


1 


2; { Destination 


notPatOr 


ss 


1 


3; { Destination 


notPatXor 


= 


1 


4; { Destination 


notPatBic 


= 


1 


5; { Destination 



= Source } 

- Source OR Destination } 
■= Source XOR Destination } 

- Source BIC Destination } 

- NOT( Source) } 

- NOT(Source) OR Destination } 

- NOT(Source) XOR Destination } 

- NOT(Source) BIC Destination } 

- Pattern } 

- Pattern OR Destination } 

- Pattern XOR Destination } 
= Pattern BIC Destination } 
= NOT(Pattern) } 

= NOT(Pattern) OR Destination } 
= NOT(Pattern) XOR Destination } 
= NOT(Pattern) BIC Destination } 



6i c 



.1 
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^ft 



^ 



^ 



TYPE WordPtr = "It 

Str255 = C §trin t |J 255]; 

Pattern = PACKED ARRAY[0..7] OF 0..255; 
Bitsl6 = ARRAY[0..15] OF INTEGER; 
VHSelect = (v,h); 

Point = RECORD CASE INTEGER OF 

0: (v: INTEGER; 
h: INTEGER); 

1: (vh: ARRAY [VHSelect] OF INTEGER); 

END; 

Rect = RECORD CASE INTEGER OF 



0: (top: 


INTEGER; 


left: 


INTEGER; 


bottom: 


INTEGER; 


right: 


INTEGER) ; 


1: (topLeft 


: Point; 


botRight: Point); 


END; 




BitMap = RECORD 




baseAddr: 


WordPtr; 


rowBytes: 


INTEGER; 


bounds: 


Rect; 


END; 




Cursor = RECORD 




data: 


Bitsl6; 


mask: 


Bitsl6; 


hotSpot: 


Point; 


END; 




CharStyle = RECORD 




fontPt 


r: Handle; 


mode: 


INTEGER; 


bold: 


INTEGER; 


slant: 


INTEGER; 


extra: 


INTEGER; 


shadow 


: INTEGER; 


END; 




PenState = RECORD 




pnLoc : 


Point; 


pnSize 


: Point; 


pnMode 


: INTEGER; 


pnPat : 


Pattern 


END; 


■' 
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RgnHandle = "RgnPtr; 


RgnPtr = "Region; 


Region = RECORD 


rgnSize: INTEGER; { rgnSize = 10 for rectangular } 


rgnBBox: Rect; 


{ more data if not rectangular } 


END; 


GrafPtr = ~GrafPort; 


GrafPort = RECORD 


portBits: BitMap; 


portRect: Rect; 


visRgn: RgnHandle; 


clipRgn: RgnHandle; 


bkPat: Pattern; 


chStyle: Charstyle; 


pnLoc: Point; 


pnSize: Point; 


pnMode: INTEGER; 


pnPat: Pattern; 


END; 


VAR thePort: GrafPtr; 


whi te , black.gr ay, ltGr ay, dkGr ay: Pattern; 


arrow: Cursor; 


graf Error: INTEGER; 


grafDebug: BOOLEAN; 


screenBits: BitMap; 


charNormal: Char Style; 


swapFont: ProcPtr; 


rgnSave: BOOLEAN; 


Housekeeping and GrafPort Procedures 


PROCEDURE InitGraf; - 


PROCEDURE OpenPort (gp: GrafPtr); 


PROCEDURE SetPort (gp: GrafPtr); 


PROCEDURE GetPort (VAR gp: GrafPtr); 


PROCEDURE SetPortBits(bm: BitMap); 


PROCEDURE PortSize (width, height: INTEGER); 


PROCEDURE MovePortTo (lef tGlobal.topGlobal: INTEGER); 


PROCEDURE SetOrigin (h,v: INTEGER); 


PROCEDURE SetVisRgn (rgn: RgnHandle); 


PROCEDURE GetVisRgn (VAR rgn: RgnHandle); 


PROCEDURE SetClipRgn (rgn: RgnHandle); 


PROCEDURE GetClipRgn (VAR rgn: RgnHandle); 


PROCEDURE ClipRect (r: Rect); 


PROCEDURE BackPat (pat: Pattern); 
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Cursor Handling 




PROCEDURE SetCursor 
PROCEDURE HideCursor; 
PROCEDURE ShowCursor; 
PROCEDURE CursorVis 


(crsr: Cursor); 
(visible: BOOLEAN); 


Pen and Line Drawing 


PROCEDURE GetPen 
PROCEDURE GetPenState 
PROCEDURE SetPenState 
PROCEDURE PenSize 
PROCEDURE PenMode 
PROCEDURE PenPat 
PROCEDURE PenNormal; 
PROCEDURE MoveTo 
PROCEDURE Move 
PROCEDURE LineTo 
PROCEDURE Line 


(VAR pt: Point); 
(VAR pnState: PenState); 
(pnState: PenState); 
(width, height: INTEGER); 
(mode: INTEGER); 
(pat: Pattern); 

(h,v: INTEGER); 
(dh.dv: INTEGER); 
(h,v: INTEGER); 
(dh.dv: INTEGER); 


Character Drawing 




PROCEDURE DrawChar 
PROCEDURE DrawString 
PROCEDURE DrawText 
FUNCTION CharWidth 
FUNCTION StringWidth 
FUNCTION TextWidth 
PROCEDURE SetChar 


(ch: char); 

(s: Str255); 

(textBuf: WordPtr; f IrstByte.byteCount: INTEGER); 

(ch: CHAR): INTEGER; 

(s: Str255): INTEGER; 

(textBuf: WordPtr; f irstByte.byteCount: INTEGER): INTEGER; 

(chS: CharStyle); 


Calculations with 


Rectangles 


PROCEDURE SetRect 
PROCEDURE OffsetRect 
PROCEDURE InsetRect 
FUNCTION SectRect 
FUNCTION PtInRect 


(VAR r: Rect; left, top, right, bottom: INTEGER); 

(VAR r: Rect; dh.dv: INTEGER); 

(VAR r: Rect; dh.dv: INTEGER); , 

(srcRectA.srcRectB: Rect; VAR dstRect: Rect): BOOLEAN; 

(pt: Point; r: Rect): BOOLEAN; 


Graphical) Operations on Rectangles 


PROCEDURE FrameRect 
PROCEDURE PaintRect 
PROCEDURE EraseRect 
PROCEDURE InvertRect 
PROCEDURE FillRect 
PROCEDURE ScrollRect 
PROCEDURE XferRect 


(r: Rect); 
(r: Rect); 
(r: Rect); 
(r: Rect); 

(r: Rect; pat: Pattern); 

(dstRect: Rect; dh.dv: INTEGER; updateRgn: rgnHandle); 
(srcBits.dstBits: BitMap; srcRect, dstRect: Rect; 
mode: INTEGER; pat:Pattern); 


2/15/82 Espinosa 


/QUICK. DRAW/ QUIKDRAW . 7 


QuickDraw Programmer's Gu 


"de • 15 February 1982 


Page 0061 of 0064 4 



t > 
Apple Macintosh Early Technical Information • Inside Macintosh 


SUMMARY OF QUICKDRAW 61 


Graphical/ Operations on Ovals 




PROCEDURE YrameOval (r: Rect); 




PROCEDURE PaintOval (r: Rect); 




PROCEDURE EraseOval (r: Rect); 




PROCEDURE InvertOval (r: Rect); 




PROCEDURE FillOval (r: Rect; pat: Pattern); 




Graphic^ Operations on Rounded-Corner Rectangles 




PROCEDURE FrameRoundRect (r: Rect; ovalWidth,ovalHeight : 


INTEGER) ; 


PROCEDURE PaintRoundRect (r: Rect; ovalWidth.ovalHeight: 


INTEGER) ; 


PROCEDURE EraseRoundRect (r: Rect; ovalWidth.ovalHeight: 


INTEGER) ; 


PROCEDURE InvertRoundRect (r: Rect; ovalWidth.ovalHeight: 


INTEGER) ; 


PROCEDURE FillRoundRect (r: Rect; ovalWidth.ovalHeight: 


INTEGER; pat: Pattern); 


Calculations with Regions 




FUNCTION NewRgn: RgnHandle; 




PROCEDURE DisposeRgn(rgn: RgnHandle); 




PROCEDURE CopyRgn (srcRgn, dstRgn: RgnHandle); 




PROCEDURE SetRectRgn(rgn: RgnHandle; left, top, right, bottom: INTEGER); 


PROCEDURE RectRgn (rgn: RgnHandle; r: Rect); 




PROCEDURE OpenRgn; 




PROCEDURE CloseRgn (dstRgn: RgnHandle); 


i 


PROCEDURE OffsetRgn (rgn: RgnHandle; dh.dv: INTEGER); 




PROCEDURE InsetRgn (rgn: RgnHandle; dh.dv: INTEGER); 




PROCEDURE SectRgn (srcRgnA.srcRgnB.dstRgn: RgnHandle); 




PROCEDURE UnionRgn (srcRgnA^srcRgnB, dstRgn: RgnHandle); 




PROCEDURE DiffRgn (srcRgnA,srcRgnB, dstRgn: RgnHandle); 




PROCEDURE XorRgn (srcRgnA,srcRgnB, dstRgn: RgnHandle); 




FUNCTION PtlnRgn (pt: Point; rgn: RgnHandle): BOOLEAN; 




FUNCTION RectlnRgn (r: Rect; rgn: RgnHandle): BOOLEAN; 




FUNCTION EqualRgn (rgnA, rgnB: RgnHandle): BOOLEAN; 




FUNCTION EmptyRgn (rgn: RgnHandle): BOOLEAN; 




Graphic^ Operations on Regions 




PROCEDURE FrameRgn (rgn: RgnHandle); 




PROCEDURE PaintRgn (rgn: RgnHandle); 




PROCEDURE EraseRgn (rgn: RgnHandle); 




PROCEDURE InvertRgn (rgn: RgnHandle); 




PROCEDURE FillRgn (rgn: RgnHandle; pat: Pattern); 




PROCEDURE XferRgn (srcBits.dstBits: BitMap; srcRect.dstRect: Rect; 


mode:|INTEGER; pat :Pat tern; maskRgn: 


RgnHandle); 


Miscellaneous Utility Routines 




FUNCTION Random: INTEGER; 




FUNCTION GetPixel (h,v: INTEGER): BOOLEAN; 




PROCEDURE AddPt (src: Point; VAR dst: Point); 


- 


PROCEDURE SubPt (src: Point; VAR dst: Point); 




PROCEDURE SetPt (VAR pt :" Point; h,v: INTEGER); 




PROCEDURE LocalToGlobal (VAR pt : Point); 
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PROCEDURE GlobalToLo 


:al (VAR pt : 


Point); / 


PROCEDURE StuffHex 


( thingptt 


•: WordFtr; s:jstr255); 


DEFAULT VALUES 


These default values 
InitGraf procedure: 


are set when 


you initialize MacGraf with the 






Global 


Type 


Setting 


white 


Pattern 


All-white pattern" 


black 


Pattern 


All-black pattern 


gray 


Pattern 


50% grey pattern 


ltGray 


Pattern 


33% grey pattern 


dkGray 


Pattern 


66% grey pattern 


arrow 


Cursor 


Pointing arrow cursor 


charNormal 


charStyle 


NO FONT, OR mode, no extras 


screenBlts 


BitMap 


Macintosh screen, (0,0,384,256) 


thePort 


GrafPtr 


NIL 


rgnSave 


BOOLEAN 


FALSE 


These default values 


for a single 


Graf Port are set by OpenPort: 


Variable 


Type 


Setting 


portBits 


BitMap 


ScreenBits (see InitGraf) 


portRect 


Rect 


ScreenBlts. bounds (0,0,384,256) 


visRgn~~ 


Region 


Rectangular, (0,0,384,256) 


clipRgn~~ 


Region 


Rectangular , ( -30000 , -30000 , 30000 , 30000) 


bkPat 


Pattern 


White 


chStyle 


CharStyle 


CharNormal 


pnLoc 


Point 


(0,0) 


pnSize 


Point 


(l.D 


pnMode 


INTEGER 


patCopy (8) 


pnPat 


Pattern 


Black ^ 
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